pSeries - DLPAR Scripts, TIPS0121
DLPAR scripts are written by system administrators or software vendors to automate system
resources in a dynamic LPAR environment. Scripts can be implemented in any scripting
language, such as perl or shell, or it can be a compiled program. They are maintained by the
system administrator using the drmgr command. The following Tip provides an overview of how
to craft a script
DLPAR scripts, used to automate LPAR reconfiguration, are written by system administrators or
software vendors. Scripts can be implemented in any scripting language, such as perl or shell, or
it can be a compiled program. They are maintained by the system administrator using the drmgr
command. The syntax of the command is as follows:
drmgr { -i script_name [-w minutes ] [ -f ] | -u script_name } [ -D
hostname ]
drmgr [ -b ]
drmgr [ -R script_install_root_directory ]
drmgr [ -S syslog_ID ]
drmgr [ -l ]
Descriptions of the most important flags for the drmgr command are provided in the following
table. For a complete reference, refer to the man page or the documentation.
Table 1. Flags of the drmgr command
Flags Description
-i script_name This flag is used to install a script specified by the
script_name parameter. By default, scripts are installed
in the /usr/lib/dr/scripts/all directory.
-w minutes This flag is used to override the time limit value
specified by the vendor for the script. The script will be
ended if it exceeds the specified time limit.
-f Using this flag forces an installed script to be
overwritten.
-u script_name This flag is used to uninstall a script specified by the
script_name parameter.
-l This option will display the details regarding the DLPAR
scripts that are currently installed.
For example, to install the /root/root_dlpar_test.sh script in the default directory, the following
command could be used:
drmgr -i /root/root_dlpar_test.sh
To list the details, the drmgr -l command is used. The output is similar to the following:
DR Install Root Directory: /usr/lib/dr/scripts
Syslog ID: DRMGR
------------------------------------------------------------
/usr/lib/dr/scripts/all/root_lpar_test.sh DLPAR test script
Vendor:IBM, Version:1.0, Date:19092002
Script Timeout:10, Admin Override Timeout:0
Resources Supported:
Resource Name: cpu Resource Usage: root_dlpar_test.sh command
[parameter]
------------------------------------------------------------
DLPAR scripts get notified at each of the DLPAR operation phases explained previously.
Notifying DLPAR scripts involves invoking the scripts in the appropriate environment with the
appropriate parameters.
The environment the script is executed in is as follows:
The execution user ID and group ID are set to the uid or gid of the script.
The PATH environment is set to /usr/bin:/etc:/usr/sbin.
The working directory is /tmp.
Environment variables that describe the DLPAR event are set.
DLPAR scripts can write any necessary output to stdout. The format of the output should be
name=value pair strings separated by newline characters to relay specific information to the
drmgr. For example, the output DR_VERSION=1.0 could be produced with the following ksh
command:
echo “DR_VERSION=1.0“
Error and logging messages are provided by DLPAR scripts in the same way as regular output by
writing name=value pairs to stdout. The DR_ERROR=message pair should be used to provide
error descriptions. The name=value pairs contain information to be used to provide error and
debug output for the syslog.
DLPAR scripts can also write additional information to stdout that will be reflected to the HMC.
The level of information that should be provided is based on the detail level passed to the script in
the DR_DETAIL_LEVEL=N environment variable. N must be in the range of 0 to 5, where the
default value of zero (0) signifies no information. A value of one (1) is reserved for the operating
system and is used to present the high-level flow. The remaining levels (2-5) can be used by the
scripts to provide information with the assumption that larger numbers provide greater detail.
The syntax the DLPAR script is invoked with is as follows:
[ input_name1=value1 ... ] scriptname command [ input_parameter1 ... ]
Input variables are set as environment variables on the command line, followed by the script to be
invoked that is provided with a command and with further parameters. A description of the
function the commands should perform is provided in the following table. If the script is called with
a command that is not implemented, it should exit with a return code of 10.
Table 2. DLPAR script commands
Command and parameter Description
scriptinfo Identifies the version, date, and vendor of
the script. It is called when the script is
installed.
register Identifies the resources managed by the
script. If the script returns the resource
name (cpu or mem), the script will be
automatically invoked when DLPAR
attempts to reconfigure processors and
memory, respectively. The register
command is called when the script is
installed with the DLPAR subsystem.
usage resource_name Returns information describing how the
resource is being used by the application.
The description should be relevant so that
the user can determine whether to install or
uninstall the script. It should identify the
software capabilities of the application that
are impacted. The usage command is
called for each resource that was identified
by the register command.
checkrelease Indicates whether the DLPAR subsystem
resource_name should continue with the removal of the
named resource. A script might indicate that
the resource should not be removed if the
application is not DLPAR-aware and the
application is considered critical to the
operation of the system.
prerelease resource_name Reconfigures, suspends, or terminates the
application so that its hold on the named
resource is released.
postrelease resource_name Reconfigures, resumes, or restarts the
application.
undoprerelease Invoked if an error is encountered and the
resource_name resource is not released. Operations done
in the prerelease command should be
undone.
checkacquire Indicates whether the DLPAR subsystem
resource_name should proceed with the resource addition. It
might be used by a license manager to
prevent the addition of a new resource, for
example, cpu, until the resource is licensed.
preacquire resource_name Used to prepare for a resource addition.
undopreacquire Invoked if an error is encountered in the
resource_name preacquire phase or when the event is
acted upon. Operations performed in the
preacquire command should be undone.
postacquire resource_name Reconfigure, resume, or start the
application.
The input variables that are provided as environment variables are dependent on the resource
that is operated on. For memory add and remove operations, the variables provided in the
following table are provided (one frame is equal to 4 KB):
Table 3. Input variables for memory add/remove operations
Input variable Description
DR_FREE_FRAMES=0xFFFFFFFF The number of free frames currently in
the system, in hexadecimal format.
DR_MEM_SIZE_COMPLETED=n The number of megabytes that were
successfully added or removed, in
decimal format.
DR_MEM_SIZE_REQUEST=n The size of the memory request in
megabytes, in decimal format.
DR_PINNABLE_FRAMES=0xFFFFFFFF The total number of pinnable frames
currently in the system, in hexadecimal
format. This parameter provides
valuable information when removing
memory in that it can be used to
determine when the system is
approaching the limit of pinnable
memory, which is the primary cause of
failure for memory remove requests.
DR_TOTAL_FRAMES=0xFFFFFFFF The total number of frames currently in
the system, in hexadecimal format.
The environment variables provided in the following table are set for processor add and remove
operations:
Table 4. Input variables for processor add/remove operations
Input Variable Description
DR_BCPUID=N The bind CPU ID of the processor that
is being added or removed in decimal
format. A bindprocessor attachment to
this processor does not necessarily
mean that the attachment has to be
undone. This is only true if it is the Nth
processor in the system, because the
Nth processor position is the one that
is always removed in a CPU remove
operation. Bind IDs are consecutive in
nature, ranging from 0 to N and are
intended to identify only online
processors. Use the bindprocessor
command to determine the number of
online CPUs.
DR_LCPUID=N The logical CPU ID of the processor
that is being added or removed in
decimal format.
In the following example, an example Korn shell script in given that can be installed. For simplicity
and demonstration purposes this script does not take any action. The actions for the process to
control would need to be included in the appropriate command section:
#!/usr/bin/ksh
if [[ $# -eq 0 ]]
then
echo "DR_ERROR= Script usage error"
exit 1
fi
ret_code=0
command=$1
case $command in
scriptinfo )
echo "DR_VERSION=1.0"
echo "DR_DATE=19092002"
echo "DR_SCRIPTINFO=DLPAR test script"
echo "DR_VENDOR=IBM";;
usage )
echo "DR_USAGE=root_dlpar_test.sh command [parameter]";;
register )
echo "DR_RESOURCE=cpu";;
checkacquire )
:;;
preacquire )
:;;
undopreaquire )
:;;
postacquire )
:;;
checkrelease )
:;;
prerelease )
:;;
undoprerelease )
:;;
postrelease )
:;;
* )
ret_code=10;;
esac
exit $ret_code