Scripts

The scripts API can be used to read view and modify the scripts which NSClient++ can run.

Runtimes

As scripts can be provided by multiple plugins (LUAScripts, PythonScripts and CheckExternalScripts) there is a runtime selector which will send the information to the proper runtime. Currently only external scripts are supported.

Key Runtime Description Status
ext CheckExternalScripts Any script which ix executed on command line Complete
lua LUAScripts Scripts written in the Lua language which is executed inside NSClient++ Missing
py PythonScripts Scripts written in the Python language running inside NSClient++ Complete

Security

As a security mechanism only scripts residing in the configured script root folder is showed.

To configure the script root you can add the following to you configuration.

[/settings/external scripts]
script root=${scripts}

List Runtimes

The API lists all available runtimes.

Key Value
Verb GET
Address /api/v1/scripts
Privilege scripts.list.runtimes

Request

GET /api/v1/scripts

Response

[
  {
    "module":"CheckExternalScripts",
    "name":"ext",
    "title":"CheckExternalScripts"
  }
]

Example

Fetch a list of all runtimes with curl

curl -s -k -u admin https://localhost:8443/api/v1/scripts |python -m json.tool
[
    {
        "ext_url": "https://localhost:8443/api/v1/scripts/ext",
        "module": "CheckExternalScripts",
        "name": "ext",
        "title": "CheckExternalScripts"
    }
]

List Scripts

The API lists all available commands/scripts for a given runtime.

Key Value
Verb GET
Address /api/v1/scripts/:runtime
Privilege scripts.lists.:runtime

Parameters

Key Value Description
all true / false If all scripts should be listed (not activated ones)

Request

GET /api/v1/scripts/ext

Response

[
  'check_ok'
]

Example 1: Listing active script

Fetch all active (currently enabled) scripts from CheckExternalScripts.

curl -s -k -u admin https://localhost:8443/api/v1/scripts/ext |python -m json.tool
[
    "check_ok"
]

Example 2: Listing all scripts

Request

curl -s -k -u admin https://localhost:8443/api/v1/scripts/ext?all=true |python -m json.tool
[
    "scripts\\check_60s.bat",
    "scripts\\check_battery.vbs",
    "scripts\\check_files.vbs",
    "scripts\\check_long.bat",
    "scripts\\check_no_rdp.bat",
    "scripts\\check_ok.bat",
    "scripts\\check_ping.bat",
    "scripts\\check_printer.vbs",
    "scripts\\check_test.bat",
    "scripts\\check_test.ps1",
    "scripts\\check_test.vbs",
    "scripts\\check_updates.vbs",
    "scripts\\lua\\check_cpu_ex.lua",
    "scripts\\lua\\default_check_mk.lua",
    "scripts\\lua\\noperf.lua",
    "scripts\\lua\\test.lua",
    "scripts\\lua\\test_ext_script.lua",
    "scripts\\lua\\test_nrpe.lua",
    "scripts\\powershell.ps1"
]

Fetch Script

Fetch the script definition (ext) and/or the actual script.

Key Value
Verb GET
Address /api/v1/scripts/:runtime/:script
Privilege scripts.get.:runtime

Request

GET /api/v1/scripts/ext/check_ok

Response

scripts\check_ok.bat "Everything will be fine"

Example 1: Show command definitions

Show the commands definitions i.e. the configured command which will be executed when the check is executed.

curl -s -k -u admin https://localhost:8443/api/v1/scripts/ext/check_ok
scripts\check_ok.bat "The world is always fine..."

Example 2: Listing the actual script

Please note that since script definitions are really commands there is no automated way to go from a script definition and its script. But given the above definition we can discern that the script is called scripts\check_ok.bat. We can use either / or \ as path separator here.

curl -s -k -u admin https://localhost:8443/api/v1/scripts/ext/scripts/check_ok.bat
@echo OK: %1
@exit 0

Add Script

Upload the new script definitions. Please note that it is not possible to upload scripts to the same granularity as you can with the configuration. For that you have to use the configuration API instead. This API is designed for convenience. So for instance you cannot set arguments for scripts via this API.

Key Value
Verb PUT
Address /api/v1/scripts/:runtime/:script
Privilege scripts.add.:runtime

Request

PUT /api/v1/scripts/ext/scripts\check_new.bat

The posted payload

The payload we post is the actual script such as:

@echo OK: %1
@exit 0

Response

Added check_new as scripts\check_new.bat

Example

Given a file called check_new.bat which contains the following:

@echo OK: %1
@exit 0

We can use the following curl call to upload that as check_new.

curl -s -k -u admin -X PUT https://localhost:8443/api/v1/scripts/ext/scripts/check_new.bat --data-binary @check_new.bat
Added check_new as scripts\check_new.bat

configuration

The configuration added to execute this script is:

[/settings/external scripts/scripts]

; SCRIPT - For more configuration options add a dedicated section (if you add a new section you can customize the user and various other advanced features)
check_new = scripts\check_new.bat

Delete Script

Delete both script definitions and actual script files from disk.

Key Value
Verb DELETE
Address /api/v1/scripts/:runtime/:script
Privilege scripts.delete.:runtime

Request

DELETE /api/v1/scripts/ext/scripts\check_new.bat

Response

Script file was removed

Example 1: Delete the script definition

If we have created a script for check_new (see adding script above) we can remove it via the API as well. Please note this will ONLY remove the script definition not the actual script file (to remove the script see below).

curl -s -k -u admin -X DELETE https://localhost:8443/api/v1/scripts/ext/check_new
Script definition has been removed don't forget to delete any artifact for: scripts\check_new

Example 2: Deleting the script file

To delete the script file we use the same trick as when we showed it above i.e. we specify the script file instead of the command name.

curl -s -k -u admin -X DELETE https://localhost:8443/api/v1/scripts/ext/scripts/check_new.bat
Script file was removed