unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.9)
Page:
Section:
Apropos / Subsearch:
optional field



File Formats                                         rcmscript(4)



NAME
     rcmscript - script interface specification for the  Reconfi-
     guration and Coordination Manager

SYNOPSIS
     rcm_scriptname scriptinfo

     rcm_scriptname register

     rcm_scriptname resourceinfo resourcename

     rcm_scriptname queryremove resourcename

     rcm_scriptname preremove resourcename

     rcm_scriptname postremove resourcename

     rcm_scriptname undoremove resourcename

DESCRIPTION
     Reconfiguration and Coordination Manager (RCM) is  a  frame-
     work  designed to coordinate device consumers during Solaris
     Dynamic Reconfiguration (DR). The  interfaces  specified  in
     this  man  page  allow device consumers, such as application
     vendors or site administrators, to act before and  after  DR
     operations  take  place  by  providing  RCM scripts. You can
     write your own RCM scripts to shut down  your  applications,
     or  to  cleanly  release  the devices from your applications
     during dynamic remove operations.

     An RCM script is an executable perl script, a  shell  script
     or  a  binary. Perl is the recommended language. Each script
     is run in its own address space using  the  user-id  of  the
     script file owner.

     An RCM script is invoked on demand in response to DR as fol-
     lows:

     <scriptname> <command> [args ...]


     Every script must implement the following RCM commands:

     scriptinfo
           Get script information.

     register
           Register devices the script handles.

     resourceinfo
           Get resource information.




SunOS 5.9           Last change: 19 Feb 2003                    1






File Formats                                         rcmscript(4)



     A script might include some or all the of the following com-
     mands:

     queryremove
           Queries whether the resource can be released.

     preremove
           Releases the resource.

     postremove
           Provides post-resource removal notification.

     undoremove
           Undo the actions done in preremove.

     When a script's register command is run, the  script  should
     supply, in return data, all resource names the script or its
     application handles that could potentially be removed by DR.
     A resource name refers to a name in /dev path name.

     Below is a high-level overview of  the  sequence  of  script
     invocations  that  occurs when dynamic removal of a script's
     registered resource is attempted. See the  COMMANDS  section
     for a detailed description of the commands.

     1. Prior to removing the resource from the system during DR,
        the script's queryremove command is run:


     <scriptname> queryremove <resourcename>

     The script should check for obvious reasons why the resource
     can  not  be  removed from the perspective of its service or
     application.

     2. If the script indicates that the resource can be  removed
        in  the  queryremove command. The script's preremove com-
        mand is run:


     <scriptname> preremove <resourcename>

     The script releases the resource from the service or  appli-
     cation  represented  by  the  script  and  prepares  for the
     resource removal. Releasing the  resource  includes  closing
     the  resource  if  the  resource  is currently opened by its
     application.

     3. The system then proceeds to remove the resource.

     4. If the system has removed the resource  successfully  the
        script's postremove command is run:



SunOS 5.9           Last change: 19 Feb 2003                    2






File Formats                                         rcmscript(4)



     <scriptname> postremove <resourcename>

     Otherwise the script's undoremove command is run:

     <scriptname> undoremove <resourcename>

     For any commands the script does not implement, it must exit
     with  exit status of 2. RCM silently returns success for the
     script's unimplemented commands.

     A script performs the following basic steps:

        o  Takes RCM command and additional  arguments  from  the
           command line and environment parameters.

        o  Processes the command.

        o  Writes  the  expected  return  data   to   stdout   as
           name=value  pairs delimited by newlines, where name is
           the name of the return data item that RCM expects  and
           value is the value associated with the data item.

  Environment
     Initial environment of RCM scripts is set as follows:

        o  Process UID is set to the UID of the script.

        o  Process GID is set to the GID of the script.

        o  PATH variable is set to /usr/sbin:/usr/bin.

        o  Current working directory is set to:

              o  /var/run for scripts owned by root

              o  /tmp for scripts not owned by root

        o  File descriptor 0 (stdin) is set to /dev/null

        o  Environment variable RCM_ENV_DEBUG_LEVEL is set to the
           debug level. Logging is discussed below.

        o   The following  environment  variables  are  also  set
           where possible:


              o  LANG

              o  LC_COLLATE

              o  LC_CTYPE




SunOS 5.9           Last change: 19 Feb 2003                    3






File Formats                                         rcmscript(4)



              o  LC_MESSAGES

              o  LC_MONETARY

              o  LC_NUMERIC

              o  LC_TIME

              o  LC_ALL

              o  TZ

     See environ(5) for a description  of  these  variables.  See
     gettext(1) for details on retrieving localized messages.

     All environment variable names beginning with  RCM_ENV_  are
     reserved for use by the RCM.

     The character encoding used by the RCM and  RCM  scripts  to
     exchange  RCM  commands,  environment  parameters, and name-
     value pairs is  ASCII  unless  the  controlling  environment
     variables are specified otherwise.

  Commands
  scriptinfo
     The scriptinfo command  is  invoked  to  gather  information
     about the script.

     Return data:
           If successful, the script  must  write  the  following
           name-value pairs to stdout and exit with status 0:


              o  rcm_script_version=1

              o  rcm_script_func_info=script_func_info

              o  rcm_cmd_timeout=command_timeout_value
     where script_func_info is a localized human-readable message
     describing the functionality of the script.

     The RCM monitors the execution time of RCM commands  by  RCM
     scripts.   command_timeout_value  is  the  maximum  time  in
     seconds the script is expected to take to  process  any  RCM
     command  except  the  scriptinfo  command  itself. If an RCM
     script does not process the RCM command and exit within this
     time,  RCM sends a SIGABRT signal to the script process. RCM
     then waits for a few seconds for the script  to  finish  the
     processing  of  the  current  RCM  command  and exit. If the
     script does not exit within this time, RCM sends  a  SIGKILL
     signal to the script.




SunOS 5.9           Last change: 19 Feb 2003                    4






File Formats                                         rcmscript(4)



     The rcm_cmd_timeout name-value pair is optional. It is  only
     needed  if  the  script  is expected to take more than a few
     seconds to process any RCM command. Setting this name  to  a
     value  of  0  (zero)  disables the timer. If this name-value
     pair is not supplied, a default value  is  assigned  by  the
     RCM.

           Upon failure, the script must specify the failure rea-
           son  using  the name-value pair rcm_failure_reason and
           exit with status 1.

  register
     The register command is invoked to allow a script to specify
     the  resources that it or its application handles that could
     potentially be removed by DR. The script has to  supply  all
     its   resource  names  to  RCM  using  the  name-value  pair
     rcm_resource_name.

     Return Data:
           If successful, the script  must  write  the  following
           name-value pairs to stdout and exit with status 0:


     rcm_resource_name=resourcename
     rcm_resource_name=resourcename
                .
                .
                .

     where resourcename is the name of the resource the script is
     interested in.

          Upon failure, the script must specify the failure  rea-
          son  using  the  name-value pair rcm_failure_reason and
          exit with status 1.

  resourceinfo resourcename
     The resourceinfo command is invoked to get the usage  infor-
     mation about resourcename.

     Return Data:
           If successful, the script  must  write  the  following
           name-value pair to stdout and exit with status 0:


     rcm_resource_usage_info=resource_usage

     where resource_usage is a localized human  readable  message
     describing the usage of the resource by the script.

          Upon failure, the script must specify the failure  rea-
          son  using  the  name-value pair rcm_failure_reason and



SunOS 5.9           Last change: 19 Feb 2003                    5






File Formats                                         rcmscript(4)



          exit with status 1.

  queryremove resourcename
     Prior  to  removing  the  resource  from  the  system,   the
     queryremove command is invoked to query the script to deter-
     mine whether the script can release the given resource  suc-
     cessfully from the service or application it represents. The
     script does not actually release the resource.   The  script
     might  indicate  that it is not able to release the resource
     if the resource is critical for its service or application.

     Additional environment parameter:

     RCM_ENV_FORCE
           Can be one of:

           FALSE Normal request.

           TRUE  Request  is  urgent.  The  script  should  check
                 whether  the  resource  can be released success-
                 fully by force,  such  as  by  using  the  force
                 option to unmount a file system.


     Return Data:
           If the command succeeds, the  script  must  return  no
           data and exit with status 0.

           If the  script  would  not  be  able  to  release  the
           resource,  it  must specify the reason using the name-
           value pair rcm_failure_reason and exit with status 3.

           Upon any other failure, the script  must  specify  the
           failure    reason    using    the    name-value   pair
           rcm_failure_reason and exit with status 1.

  preremove resourcename
     The preremove command is invoked  prior  to  an  attempt  to
     remove  the  given resourcename. In response to this command
     the script can either release the resource (including  clos-
     ing  the  device if the device is currently opened) from the
     service or application it represents or indicate that it can
     not release the resource if the resource is critical for its
     service or application.

     Additional environment parameter:

     RCM_ENV_FORCE
           Can be one of:

           FALSE Normal request.




SunOS 5.9           Last change: 19 Feb 2003                    6






File Formats                                         rcmscript(4)



           TRUE  Request is urgent. The script should make  extra
                 effort to release the resource, such as by using
                 the force option to unmount a file system.


     Return Data:
           If the command succeeds, the  script  must  return  no
           data and exit with status 0.

           If the script cannot release  the  resource,  it  must
           specify   the   reason   using   the  name-value  pair
           rcm_failure_reason and exit with status 3.

           Upon any other failure, the script  must  specify  the
           failure    reason    using    the    name-value   pair
           rcm_failure_reason and exit with status 1.

  postremove resourcename
     The postremove command is invoked after  the  given  resour-
     cename has been removed.

     Return Data:
           If the command succeeds, the  script  must  return  no
           data and exit with status 0.

           Upon failure, the script must specify the failure rea-
           son  using  the name-value pair rcm_failure_reason and
           exit with status 1.

     undoremove resourcename

     The undoremove command is invoked to undo what was  done  in
     the  previous  preremove command for the given resourcename.
     The script can bring the state of the resource to  the  same
     state  it was in when the script received the preremove com-
     mand for that resource.

     Return Data:
           If the command succeeds, the  script  must  return  no
           data and exit with status 0.

           Upon failure, the script must specify the failure rea-
           son  using  the name-value pair rcm_failure_reason and
           exit with status 1.

  Logging
     A script must log all error and debug messages by writing to
     stdout  the  name-value  pairs listed below. The logged mes-
     sages  go  to  syslogd(1M)  with  the  syslog  facility   of
     LOG_DAEMON. See syslog.conf(4).

     rcm_log_err=message



SunOS 5.9           Last change: 19 Feb 2003                    7






File Formats                                         rcmscript(4)



           Logs the message with the syslog level of LOG_ERR.

     rcm_log_warn=message
           Logs the message with the syslog level of LOG_WARNING.

     rcm_log_info=message
           Logs the message with the syslog level of LOG_INFO.

     rcm_log_debug=message
           Logs the message with the syslog level of LOG_DEBUG.

     A    script    can    use    the    environment     variable
     RCM_ENV_DEBUG_LEVEL  to control the amount of information to
     log. RCM_ENV_DEBUG_LEVEL is a numeric value ranging  from  0
     to 9, with 0 meaning log the least amount of information and
     9 meaning log the most.

  Installing or Removing RCM Scripts
     You must use the following format to name a script:

     vendor,service

     where vendor is the stock symbol (or any  distinctive  name)
     of  the  vendor providing the script and service is the name
     of service the script represents.

     You must be a superuser (root) to install or remove  an  RCM
     script.

     Select one of the following directories where  you  want  to
     place the script:

     /etc/rcm/scripts
           Scripts for specific systems

     /usr/platform/`uname -i`/lib/rcm/scripts
           Scripts for specific hardware implementation

     /usr/platform/`uname -m`/lib/rcm/scripts
           Scripts for specific hardware class

     /usr/lib/rcm/scripts
           Scripts for any hardware

  Installing a Script
     To install a script, copy  the  script  to  the  appropriate
     directory  from  the  list  above, change the userid and the
     groupid of the script to the desired values, and send SIGHUP
     to rcm_daemon. For example:

     # cp SUNW,sample.pl /usr/lib/rcm/scripts
     # chown user[:group] /usr/lib/rcm/scripts/SUNW,sample.pl



SunOS 5.9           Last change: 19 Feb 2003                    8






File Formats                                         rcmscript(4)



     # pkill -HUP -x -u root rcm_daemon


  Removing a script
     Remove the script from the appropriate  directory  from  the
     list above and send SIGHUP to rcm_daemon. For example:

     # rm /usr/lib/rcm/scripts/SUNW,sample.pl
     # pkill -HUP -x -u root rcm_daemon


EXAMPLES
     Example 1: Site Customization RCM Script

     #! /usr/bin/perl -w

     #
     # A sample site customization RCM script for a tape backup application.
     #
     # This script registers all tape drives in the system with RCM.
     # When the system attempts to remove a tape drive by DR the script
     # does the following:
     #   - if the tape drive is not being used for backup, it allows the
     #     DR to continue.
     #   - if the tape drive is being used for backup, and when DR is not forced
     #     (RCM_ENV_FORCE=FALSE) it indicates that it cannot release the
     #     tape drive with appropriate error message. When forced
     #     (RCM_ENV_FORCE=TRUE) it kills the tape backup application in
     #     order to allow the DR to continue.
     #
     # This script does not implement the postremove and undoremove commands
     # since there is nothing to cleanup after DR remove operation is completed
     # or failed. If any cleanup is needed after the DR removal completed,
     # postremove command needs to implemented. If any cleanup is needed
     # in the event of DR removal failure, undoremove command needs to be
     # implemented.
     #

     use strict;

     my ($cmd, %dispatch);

     $cmd = shift(@ARGV);

     # dispatch table for RCM commands
     %dispatch = (
         "scriptinfo"    =>      do_scriptinfo,
         "register"      =>      do_register,
         "resourceinfo"  =>      do_resourceinfo,
         "queryremove"   =>      do_preremove,
         "preremove"     =>      do_preremove
     );



SunOS 5.9           Last change: 19 Feb 2003                    9






File Formats                                         rcmscript(4)



     if (defined($dispatch{$cmd})) {
         &{$dispatch{$cmd}};
     } else {
         exit (2);
     }

     sub do_scriptinfo
     {
         print "rcm_script_version=1\n";
         print "rcm_script_func_info=Tape backup appl script for DR\n";
         exit (0);
     }

     sub do_register
     {
         my ($dir, $f, $errmsg);

         $dir = opendir(RMT, "/dev/rmt");
         if (!$dir) {
             $errmsg = "Unable to open /dev/rmt directory: $!";
             print "rcm_failure_reason=$errmsg\n";
             exit (1);
         }

         while ($f = readdir(RMT)) {
             # ignore hidden files and multiple names for the same device
             if (($f !~ /^./) && ($f =~ /^[0-9]+$/)) {
                 print "rcm_resource_name=/dev/rmt/$f\n";
             }

         }

         closedir(RMT);
         exit (0);
     }

     sub do_resourceinfo
     {
         my ($rsrc, $unit);

         $rsrc = shift(@ARGV);
         if ($rsrc =~ /^/dev/rmt/([0-9]+)$/) {
             $unit = $1;
             print "rcm_resource_usage_info=Backup Tape Unit Number $unit\n";
             exit (0);
         } else {
             print "rcm_failure_reason=Unknown tape device!\n";
             exit (1);
         }
     }

     sub do_preremove



SunOS 5.9           Last change: 19 Feb 2003                   10






File Formats                                         rcmscript(4)



     {
         my ($rsrc);

         $rsrc = shift(@ARGV);

         # check if backup application is using this resource
         # if (the backup application is not running on $rsrc) {
         # allow the DR to continue
         #        exit (0);
         #}
         #
         # If RCM_ENV_FORCE is FALSE deny the operation.
         # If RCM_ENV_FORCE is TRUE kill the backup application in order
         # to allow the DR operation to proceed
         #
         if ($ENV{RCM_ENV_FORCE} eq 'TRUE') {
             if ($cmd eq 'preremove') {
                 # kill the tape backup application
             }
             exit (0);
         } else {
             #
             # indicate that the tape drive can not be released
             # since the device is being used for backup by the
             # tape backup application
             #
             print "rcm_failure_reason=tape backup in progress pid=...\n";
             exit (3);

         }
     }


EXIT STATUS
     A script must exit with following exit status values:

     0     Operation specified by the given RCM command has  been
           executed  successfully  by the script. For queryremove
           command it also means that the script can successfully
           release the resource.

     1     An error occurred while processing  the  RCM  command.
           The  script  should  provide  the error message to RCM
           using the name-value  pair  rcm_failure_reason  before
           exiting.

     2     The script does not support the given RCM  command.  A
           script  must exit with this status if it cannot under-
           stand the given RCM command.

     3     Indicates that the script cannot release the  resource
           for  preremove  and  queryremove  commands. The script



SunOS 5.9           Last change: 19 Feb 2003                   11






File Formats                                         rcmscript(4)



           should provide a message to RCM specifying the  reason
           for  not  being able to release the resource using the
           name-value pair rcm_failure_reason before exiting.

ERRORS
     If a script cannot successfully process an RCM  command,  it
     must  supply  to the RCM a message indicating the reason for
     failure by writing a name-value  pair,  in  the  form  shown
     below,  to  stdout  and  exiting  with  the appropriate exit
     status.

     rcm_failure_reason=failure_reason

     where failure_reason is a localized human  readable  message
     describing the reason for failure of the RCM command.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|


SEE ALSO
     gettext(1),  cfgadm(1M),  cfgadm_scsi(1M),   cfgadm_pci(1M),
     syslog(3C),  signal(3HEAD),  syslog.conf(4),  attributes(5),
     environ(5)

NOTES
     RCM scripts are expected to properly handle all RCM commands
     that  the script implements and to log all errors. Only root
     has permission to add or  remove  an  RCM  script.  An  ill-
     behaved RCM script can cause unexpected DR failures.

     RCM commands are invoked only for the resources  whose  sub-
     systems participate within the RCM framework. Currently, not
     all susbsystems participate within the RCM framework.














SunOS 5.9           Last change: 19 Feb 2003                   12