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