Config - Plugin

Details about managing plugins via the Rest API

Object type: plugin

Request URL: /rest/config/plugin

Methods:

  • GET - returns a list of the plugins
  • POST, PUT, DELETE - unimplemented

Parameters:

  • order - Use "num_servicechecks" to return the list ordered by servicechecks used
  • s.name - filter by name column. Use % to add wildcards

Example GET /rest/config/plugin:

{
   "list" : [
      {
         "envvars" : "",
         "name" : "check_nrpe",
         "servicechecks" : [
            {
               "name" : "/",
               "ref" : "/rest/config/servicecheck/47"
            },
            ....
            {
               "name" : "Z Drive",
               "ref" : "/rest/config/servicecheck/71"
            }
         ]
      },
      {
         "envvars" : "",
         "name" : "check_tcp",
         "servicechecks" : [
            {
               "name" : "AFS",
               "ref" : "/rest/config/servicecheck/1"
            },
            ....
            {
               "name" : "X.400",
               "ref" : "/rest/config/servicecheck/32"
            }
         ]
      },
      {
         "envvars" : "",
         "name" : "check_snmp_linkstatus",
         "servicechecks" : [
            {
               "name" : "Discards",
               "ref" : "/rest/config/servicecheck/101"
            },
            {
               "name" : "Errors",
               "ref" : "/rest/config/servicecheck/100"
            },
            {
               "name" : "Interface",
               "ref" : "/rest/config/servicecheck/95"
            }
         ]
      }
   ],
   "summary" : {
      "allrows" : "125",
      "page" : "1",
      "rows" : "3",
      "totalpages" : "42",
      "totalrows" : "125"
   }
}

URL: /rest/config/plugin/PLUGINNAME

Methods:

  • DELETE - Deletes this plugin from the database and removes from the list of plugins in the master server
  • GET, POST, PUT - unimplemented

Note: if you have the plugin on a remote collector, this will not be removed.

Plugin - Upload

  • ADMINACCESS only. Plugin is staged and executed to test if the plugin is appropriate.

URL: /rest/config/plugin/upload
Method:

  • POST - upload new plugin

When uploading:

  • Check for config->{"Controller::Settings"}->{allow_plugin_upload} and fail if not true
  • Audit log to say uploading a plugin. Log errors to opsview-web.log
  • check if plugin already exists
  • execute plugin with -h. Returns return_code, stderr and stdout

Parameters:

  • filename - file name to upload. File must begin with "check_". Filename must not contain ".." or "/" or spaces
  • changelog - if Change Log is enabled, this must be set with a message

Returns for a failure:

{
 success: false,                 // or true
 error: "Plugin already exists", // If success is false, will return an internationalised string for display
 detail: "File not found",       // May exist if success is false. Will have further information about failure
}

Returns for a success:

{
 return_code: 0,                                          // Return code of script
 stdout: 'text from plugin running -h\nwith extra lines', // Output from plugin
 stderr: '',                                              // Stderr from plugin
 exists: true,                                            // Returns true if a plugin of the same name is already live
 valid_plugin: true,                                      // This is a valid plugin based on heuristics. Could return false
}

Plugin - Import

  • Needs ADMINACCESS. Needs changelog. Check plugin again.

URL: /rest/config/plugin/import

Method:

  • POST - make new plugin live
  • Audit log when submitted. Log errors to opsview-web.log.
  • Removes plugin from staging area and copies to live.

When importing:

  • Check for config->{"Controller::Settings"}->{allow_plugin_upload} and fail if not true

Parameters:

  • filename - plugin to migrate from staging to live
  • overwrite - default 0. If 1, allow overwriting of plugin
  • changelog - required if changelog is enabled

Returns:

{ success: true }