Building a VCS Agent for FileOnOff Resources

The following sections describe different ways to build a VCS agent for "FileOnOff" resources. For test purposes, instructions for installing the agent on a single VCS system are also provided. For multi-system configurations, you must install the agent on each system in the cluster.

The examples assume that VCS is installed under /opt/VRTSvcs. If your VCS installation directory is different, change the commands accordingly.

A FileOnOff resource represents a regular file. The FileOnOff online entry point creates the file if it does not already exist. The FileOnOff offline entry point deletes the file. The FileOnOff monitor entry point returns online and confidence level 100 if the file exists; otherwise, it returns offline. The examples in this chapter use the following type and resource definitions:

The resource name and ArgList attribute values are passed to the script entry points as command-line arguments. For example, in the preceding configuration, script entry points receive the resource name as the first argument, and PathName as the second.

Using Script Entry Points

The following example shows how to build the FileOnOff agent without writing and compiling any C++ code. This example implements the online, offline, and monitor entry points only.

1. Create the directory /opt/VRTSvcs/bin/FileOnOff:
      # mkdir /opt/VRTSvcs/bin/FileOnOff
2. Use the VCS agent /opt/VRTSvcs/bin/ScriptAgent as the FileOnOff agent. Copy this file to /opt/VRTSvcs/bin/FileOnOff/FileOnOffAgent, or create a link.

   To copy the agent binary:

   
      # cp /opt/VRTSvcs/bin/ScriptAgent
        /opt/VRTSvcs/bin/FileOnOff/FileOnOffAgent

   To create a link to the agent binary:

   
      # ln -s /opt/VRTSvcs/bin/ScriptAgent
        /opt/VRTSvcs/bin/FileOnOff/FileOnOffAgent
3. Implement the online, offline, and monitor entry points using scripts.
   1. Using any editor, create the file /opt/VRTSvcs/bin/FileOnOff/online with the contents:
   
        # !/bin/sh
        # Create the file specified by the PathName attribute.
        touch $2
   2. Create the file /opt/VRTSvcs/bin/FileOnOff/offline with the contents:
   
        # !/bin/sh
        # Remove the file specified by the PathName attribute.
        rm $2
   3. Create the file /opt/VRTSvcs/bin/FileOnOff/monitor with the contents:
   
        # !/bin/sh
        # Verify file specified by the PathName attribute exists.
        if test -f $2
        then exit 110;
        else exit 100;
        fi
4. Additionally, you can implement the info and action entry points. For the action entry point, create a subdirectory named "actions" under the agent directory, and create scripts with the same names as the action_tokens within the subdirectory.

Using VCSAgStartup() and Script Entry Points

The following example shows how to build the FileOnOff agent using your own VCSAgStartup entry point. This example implements the VCSAgStartup, online, offline, and monitor entry points only.

1. Create the directory /opt/VRTSvcs/src/agent/FileOnOff:
      # mkdir /opt/VRTSvcs/src/agent/FileOnOff
2. Copy the contents from the directory /opt/VRTSvcs/src/agent/Sample
   to the directory you created in the previous step:
      # cp /opt/VRTSvcs/src/agent/Sample/*
        /opt/VRTSvcs/src/agent/FileOnOff
3. Change to the new directory:
      cd /opt/VRTSvcs/src/agent/FileOnOff
4. Edit the file agent.C and modify the VCSAgStartup() function (the last several lines) to match the following example:
      void VCSAgStartup() {
        VCSAgV40EntryPointStruct ep;
        // Set all the entry point fields to NULL because
        // this example does not implement any of them
        // using C++.
    
        ep.open = NULL;
        ep.close = NULL;
        ep.monitor = NULL;
        ep.online = NULL;
        ep.offline = NULL;
        ep.attr_changed = NULL;
        ep.clean = NULL;
        ep.shutdown = NULL;
        ep.action = NULL;
        ep.info = NULL;
           VCSAgSetLogCategory(10041);
        VCSAgRegisterEPStruct(V40, &ep);
      }
5. Compile agent.C and build the agent by invoking make. (Makefile is provided.)
      # make
6. Create the directory /opt/VRTSvcs/bin/FileOnOff:
      # mkdir /opt/VRTSvcs/bin/FileOnOff
7. Install the FileOnOff agent built in step 5.
      # make install AGENT=FileOnOff
8. Implement the online, offline, and monitor entry points, as instructed in step 3.

Using C++ and Script Entry Points

The following example shows how to build the FileOnOff agent using your own VCSAgStartup entry point, the C++ version of the monitor entry point, and the script version of online and offline entry points. This example implements the VCSAgStartup, online, offline, and monitor entry points only.

1. Create the directory /opt/VRTSvcs/src/agent/FileOnOff:
      # mkdir /opt/VRTSvcs/src/agent/FileOnOff
2. Copy the contents from the directory /opt/VRTSvcs/src/agent/Sample
   to the directory you created in the previous step:
      # cp /opt/VRTSvcs/src/agent/Sample/*
        /opt/VRTSvcs/src/agent/FileOnOff
3. Change to the new directory:
      # cd /opt/VRTSvcs/src/agent/FileOnOff
4. Edit the file agent.C and modify the VCSAgStartup()function (the last several lines) to match the following example:
       void VCSAgStartup() 
         {
       VCSAgV40EntryPointStruct ep;
       // This example implements only the monitor entry
       // point using C++. Set all the entry point
       // fields, except monitor, to NULL.
       ep.open = NULL;
       ep.close = NULL;
       ep.monitor = file_monitor;
       ep.online = NULL;
       ep.offline = NULL;
       ep.attr_changed = NULL;
       ep.clean = NULL;
       ep.shutdown = NULL;
       ep.action = NULL;
       ep.info = NULL;
         VCSAgSetLogCategory(10041);
       VCSAgRegisterEPStruct(V40, &ep);
       }
5. Modify the file_monitor() function:
      // This is a C++ implementation of the monitor entry
      // point for the FileOnOff resource type. This function
      // determines the status of a FileOnOff resource by
      // checking if the corresponding file exists. It is
      // assumed that the complete pathname of the file will
      // be passed as the first ArgList attribute.
      VCSAgResState file_monitor(const char *res_name, void
        **attr_val,int *conf_level) {
      // Initialize the OUT parameters.
      VCSAgResState state = VCSAgResUnknown;
      *conf_level = 0;
      if (attr_val) {
       // Get the pathname of the file.
       const char *path_name = (const char *) attr_val[0];
       // Determine if the file exists.
       struc stat stat_buf;
       if (stat(path_name, &stat_buf) == 0) {
        state = VCSAgResOnline;
        *conf_level = 100;
       }
       else  {
        state = VCSAgResOffline;
        *conf_level = 0;
       }
      }
   
      // Return the status of the resource.
   
      return state;
      }
6. Compile agent.C and build the agent by invoking make. (Makefile is provided.)
      # make
7. Create the directory /opt/VRTSvcs/bin/FileOnOff:
      # mkdir /opt/VRTSvcs/bin/FileOnOff
8. Install the FileOnOff agent built in step 6.
      # make install AGENT=FileOnOff

   ---

     Note    Implement the online and offline entry points as instructed in step 3.

   ---

Using C++ Entry Points

The example in this section shows how to build the FileOnOff agent using your own VCSAgStartup entry point and the C++ version of online, offline, and monitor entry points. This example implements the VCSAgStartup, online, offline, and monitor entry points only.

1. Edit the file agent.C and modify the VCSAgStartup() function
   (the last several lines) to match the following example:
      void VCSAgStartup() {
       VCSAgV40EntryPointStruct ep;
       // This example implements online, offline, and monitor
       // entry points using C++. Set the corresponding fields
       // of VCSAgV40EntryPointStruct passed to VCSAgRegisterEPStruct.
       // Set all other fields to NULL.
       ep.open = NULL;
       ep.close = NULL;
       ep.monitor = file_monitor;
       ep.online = file_online;
       ep.offline = file_offline;
       ep.attr_changed = NULL;
       ep.clean = NULL;
       ep.shutdown = NULL;
       ep.action = NULL;
       ep.info = NULL;
      VCSAgSetLogCategory(2001);
       VCSAgRegisterEPStruct(V40, &ep);
      }
2. Modify file_online() and file_offline():
      // This is a C++ implementation of the online entry
      // point for the FileOnOff resource type. This function
      // brings online a FileOnOff resource by creating the
      // corresponding file. It is assumed that the complete
      // pathname of the file will be passed as the first
      // ArgList attribute.
   
     unsigned int
     file_online(const char *res_name, void **attr_val) {
       VCSAG_LOG_INIT(file_online);
      if (attr_val) {
       // Get the pathname of the file.
       const char *path_name = (const char *) attr_val[0];
   
      // Create the file
       int fd = creat (path_name,S_IRUSR | S_IWUSR);
       if (fd < 0) {
        // if creat() failed, send a log message to
        // the console.
        char msg [1024];
         VCSAG_LOG_MSG(VCS_ERROR, 1001, VCS_DEFAULT_FLAGS, "creat ()
         "failed for for file(%s)", path_name);
       }
       else {
        close(fd);
       }
      }
      // Completed onlining resource. Return 0 so monitor
      // can start immediately. Note that return value
      // indicates how long agent framework must wait before
      // calling the monitor entry point to check if online
      // was successful.
      return 0;
     }
   
     // This is a C++ implementation of the offline entry
     // point for the FileOnOff resource type. This function
     // takes offline a FileOnOff resource by deleting the
     // corresponding file. It is assumed that the complete
     // pathname of the file will be passed as the first
     // ArgList attribute.
     unsigned int
     file_offline(const char *res_name, void **attr_val) {
        VCSAG_LOG_INIT("file_offline");
      if (attr_val) {
       // Get the pathname of the file.
       const char *path_name = (const char *) 
                attr_val[0];
       // Delete the file
       remove (path_name);
     }
      // Completed offlining resource. Return 0 so monitor
      // can start immediately. Note that return value
      // indicates how long agent framework must wait before
      // calling the monitor entry point to check if offline
      // was successful.
      return 0;
      }
3. Modify file_monitor(), as shown on step 5.
4. Compile agent.C and build the agent by invoking make. (Makefile is provided.)
      # make
5. Create the directory /opt/VRTSvcs/bin/FileOnOff:
      # mkdir  /opt/VRTSvcs/bin/FileOnOff
6. Install the FileOnOff agent built in step 4.
      #  make install AGENT=FileOnOff