---
title: "Config - Plugin"
description: ""
url: "https://docs.itrsgroup.com/docs/opsview/6.11.7/rest-api/config/api-config-plugin/index.html"
---
## Plugin - List

Object type: plugin

Permission: `CONFIGUREVIEW`

Request URL: `/rest/config/plugin`

Methods:

- `GET` — returns a list of the plugins.
- `POST`, `PUT`, `DELETE` — unimplemented.

Parameters:

- `order` — order results. Separate values with commas to do subsorting. Possible values (suffix with `_desc` to reverse ordering):
  - `name` — order by name.
  - `uncommitted` — order by unchanged items.
  - `num_servicechecks` — order by least number of service checks.
  - `num_hostcheckcommands` — order by least number of host check commands.
- `s.name` — filter by name column. Use `%` for wildcards.
- `cols` — columns to list, comma separated. Possible values:
  - name — name of plugin.
  - uncommitted — either `0` (no change) or `1` (changed).
  - hostcheckcommands — list of host check commands using this plugin.
  - servicechecks — list of service checks using this plugin.
  - envvars — deprecated.
  - origin — either `BUILTIN` for Opsview-provided plugins or `UPLOADED` for user-uploaded plugins.
  - `execution_style` — either `COMMAND_LINE_ARGS` or `STDIN_ARGS` for user-uploaded plugins. This will be `DEFER_TO_COLLECTOR` for Opsview-provided built-in plugins. For more details, see [Secure Arguments](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/secure-arguments/index.html).

### 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"
            }
         ],
         "hostcheckcommands" : [],
         "uncommitted": "1",
         "origin_id": "0"
      },
      {
         "envvars" : "",
         "name" : "check_tcp",
         "servicechecks" : [
            {
               "name" : "AFS",
               "ref" : "/rest/config/servicecheck/1"
            },
            ....
            {
               "name" : "X.400",
               "ref" : "/rest/config/servicecheck/32"
            }
         ],
         "hostcheckcommands" : [
            {
               "name" : "tcp port 21 (FTP)",
               "ref" : "/rest/config/hostcheckcommand/13"
            },
            ....
            {
               "name" : "tcp port 161 (SNMP)",
               "ref" : "/rest/config/hostcheckcommand/14"
            }
         ],
         "uncommitted": "1",
         "origin": "BUILTIN",
         "exection_style": "DEFER_TO_COLLECTOR"
      },
      {
         "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"
            }
         ],
         "hostcheckcommands" : [],
         "uncommitted": "1",
         "origin": "BUILTIN",
         "exection_style": "DEFER_TO_COLLECTOR"
      }
   ],
   "summary" : {
      "allrows" : "125",
      "page" : "1",
      "rows" : "3",
      "totalpages" : "42",
      "totalrows" : "125"
   }
}
```

## Plugin - Delete

URL: `/rest/config/plugin/PLUGINNAME`

Permission: `CONFIGUREVIEW`

Methods:

- `DELETE` — deletes this plugin from the database and removes from the list of plugins in the master server.
- `GET`, `POST`, `PUT` — unimplemented.


**Note**


When deleting a plugin, changes will not be propagated to collector systems until Apply Changes is run.



If the plugin is built-in or actively used by a Host Check Command or Service Check, deleting it will fail.

## Plugin - Upload


**Warning**


Only import plugins from trusted sources. Uploading untrusted and unverified scripts could compromise your system's integrity.



Used for uploading plugin. The plugin is staged and executed to test if the plugin is appropriate. The plugin will not be made live until it is imported.

URL: `/rest/config/plugin/upload`

Permission: `ADMINACCESS`

Method:

- `POST` — upload new plugin.

Headers:

- Content-Type must be set to a form upload format, as the file will be uploaded.

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.

The actual plugin contents must be attached to the request as multipart form data. For example, you can use the `curl` command:

```
curl -H "Accept: text/html" -H "X-Opsview-Token: <TOKEN>" -F "x-opsview-token=<TOKEN>" -F "filename=@/path/to/plugin;type=text/plain" https://<OPSVIEW URL>/rest/config/plugin/upload
```

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
}
```

When uploading Opsview will:

- Verify that the `{allow_plugin_upload}` setting in the `{"Controller::Settings"}` configuration is set to `true`. If it is not, then fail.
- Log an Audit Log entry to indicate that a plugin is being uploaded. Log any errors to the `opsview-web.log` file.
- Check if plugin already exists.
- Execute the plugin with `-h`. Returns `return_code`, stderr, and stdout.

## Plugin - Import


**Warning**


Only import plugins from trusted sources. Importing untrusted and unverified scripts could compromise your system's integrity.



Import plugin to make live (after it has been successfully uploaded).

URL: `/rest/config/plugin/import`

Permission: `ADMINACCESS`

Method:

- `POST` — make new plugin live.

Parameters:

- `filename` — plugin to migrate from staging to live. This should match the filename of a previously successfully uploaded plugin.
- `overwrite` — default `0`. If `1`, allow overwriting of plugin.
- `changelog` — required if changelog is enabled.
- `execution_style` — either `COMMAND_LINE_ARGS` or `STDIN_ARGS`. Default is `COMMAND_LINE_ARGS`.


**Note**


Only use `STDIN_ARGS` as the execution style when importing a plugin that is compatible with the secure args feature. For more details, see [Secure Arguments](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/secure-arguments/index.html).



Returns:

```
{ success: true }
```

When importing:

- Verify that the `{allow_plugin_upload}` setting in the `{"Controller::Settings"}` configuration is set to `true`. If it is not, then fail.
- Log an Audit Log entry when submitted. Log any errors to the `opsview-web.log` file.
- Remove the plugin from staging area and copy it to live.


