How to work with custom scripts
Using Custom Scripts you can achieve executing a set of scripts on your devices, periodically reporting back your own data. You can assign different set of scripts to a different agent profile. Also, each script has assigned set of device types for which it is usable. This way you manage exactly which scripts are periodically executed on which devices.
Custom data types
The Custom Script mechanism is able to capture key-value pairs. There are three type od key-value pairs recognized and sent to the server. There are up to nine values out of each data type that could be reported by the custom scripts - thus in total, there are 27 variables recognized for each device.
- custom_num1 to custom_num9 ... the integer numbers
- The example of correct data emitted by script is custom_num1=15
- Note that no spaces around the equal sign are allowed.
- Note that the line emitted by the script must consist of only the key=value pair, no extra characters are allowed.
- custom_flo1 to custom_flo9 ... real numbers
- The example of correct data emitted by script is custom_flo3=3.25
- Note that the number must be in the form of [0-9]+.[0-9]+ otherwise it is ignored. In other words, there must be at least one digit, followed by decimal dot (not comma), followed by at least one digit.
- Note that no spaces around the equal sign are allowed.
- Note that the line emitted by the script must consist of only the key=value pair, no extra characters are allowed.
- custom_txt1 to custom_txt9 ... textual data
- The example of correct data emitted by script is custom_txt1="my text"
- Note that the double quote characters must be present at the beginning and end of the string, regardless it contains spaces inside or not.
- Note that no spaces around the equal sign are allowed.
- Note that the line emitted by the script must consist of only the key=value pair, no extra characters are allowed.
Working with reported custom data
The custom data are available at two places:
- On the Device Details screen, all the captured custom data from the device are displayed in the Custom Fields table (bottom right).
- All the custom data columns with assigned names Number 1 ... Number 9, Float 1... Float 9Text 1... Text 9 could be added to the Devices table overview under the System->Settings->Device Table Columns.
- Note that you can use sorting and filtering functionality on these columns in the Devices table.
Custom data gathering mechanism
- Once the script is executed on the device, its standard output is gathered and parsed.
- All captured values (see Custom data types above) are sent to back to the server, together with the list of the scripts that were executed.
Script preparation
- The agent is being run in the Bash shell and it in turn executes custom scripts. On many devices, there is a Busybox installed, so you cannot expect that your script is run by the same Bash as on your Linux box.
- If the device has also another interpret available than bash, you can use it to interpret the custom scripts on the first line of the script, e.g. #!/usr/bin/python will make the bash use /usr/bin/python to interpret the script.
- You need to be aware that if the script fails, there are no debugging messages or errors relayed to the server, so your best bet at preparing the script is actually this:
- Connect to the machine shell and debug the script execution there.
- The script must be runnable in the bash shell simply by specifying the script path. (execute permission is automatically added by agent when downloading it from the server)
- Script may emit whatever data you like on its standard output but all except the captured lines (e.g. custom_num2=5, see data types above) are thrown off.
- There may be no extraneous characters on the lines that are to be captured by the agent and sent over to server.
- Once you are happy with the script, you may copy paste its body into UI, specify for which device types it is intended and assign to the designed agent profiles.
- Wait until next device's contact with the server, the script gets downloaded onto the device.
- You may now connect to the device and execute the script directly from the installed path (/opt/adwarfg/custom_scripts/<script_name>) to observe it's execution after being processed by server and agent to check if it indeed produces the desired output.
If you want to see the exact data produced by the agent (including any custom script captured output) and see also any potential error messages, you can do this:
- Stop the agent via device agent UI (if agent UI available for this device type)
- Connect to device command line
- If the agent is still running (no UI), stop it by e.g. systemctl stop adwarfg or /etc/init.d/adwarfg stop or similar depending on which init system is being used on the device.
- Run the agent in the debug + one-cycle-only + keep sent data in tmp fashion:
- for Advantech devices: /opt/adwarfg/bin/dwarfg_agent.sh -d -o -cache
- for other devices: /opt/adwarfg/dwarfg_agent.sh -d -o -cache
- Next to observing the debug messages and communication log on the commandline, there are a few usefull artifacts produced in /tmp/dwarfg-tmp:
- dwarfg-cache.small ... the exact output sent to server. All the custom scripts captured key=value pairs are at the bottom in its own CUST section, together with a number of scripts which execution failed.
- custom_script_output.txt ... contains the aggregated standard output of all scripts, including the not-captured lines.
- custom_script<ID_version>.errlog ... error output from every custom script that was run. Please note that if the script did not execute, the log is empty.
How are the scripts delivered to the device?
When the device contacts the server, it sends its list of custom scripts.
For every script that is assigned to the agent profile, matches device type and is missing in the device report (or for which there is a newer script version on the server), the device obtains the download command that should be executed immediately, resulting in the script being put under /opt/adwarfg/custom_scripts directory and assigned executable permission.
For every script that is listed by the device as present on the device but NOT assigned to the agent profile or not matching the device type, the device obtains the delete command that should get executed immediately, resulting in removing the custom script from the device.
Script example
The following script reports several custom values.
#!/bin/bash
echo "custom_num1=10"
echo "custom_flo1=3.95"
echo "custom_txt1=\"some text\""