|
<< Click to Display Table of Contents >> RayVentory Scan Engine > 12.6 u4 > User Guide > Advanced Topics Custom Scripts for Non-Windows Scans |
The custom script feature for RemoteInventoryForUnix (RIU) and ndtrack basically is a new xml based language used to perform custom commands on a Unix or Linux system and to process the results of these commands. It adds more flexibility to ndtrack and RIU by enabling the execution of custom commands and storing the results in the inventory file during its creation.
Custom scripts can be used for the following operating systems:
•HP-UX
•Solaris
•macOS
•AIX
•Linux
A custom script can be execute by using either RIU or ndtrack with the following parameter:
•RIU: scriptFile=<pathToScript> (the script needs to reside on the host machine on which RIU is going to be executed)
•ndtrack: -o scriptFile=<pathToScript> (the script needs to reside on the same machine as the ndtrack.sh)
The following elements are used for custom scripts.
The root element in the XML structure in which all the custom scripts are placed.
Attributes |
Elements |
|---|---|
•Name: The name of the CustomScriptSet. •Version: The version that this CustomScriptSet and all its scripts, commands, etc. are compatible to. |
•CustomScript |
Example:
<CustomScriptSet Name="ExampleName" Version="0.1.1">
<CustomScript Name[...]>
</CustomScriptSet>
A container for a list of commands that are to be executed. A foreachline loop and/or the item which is written into the inventory file.
Attributes |
Elements |
|---|---|
•Name: The name of the CustomScript that is executed. •TargetPlatform (optional): Used to specify the target platform on which the custom script shoudl be executed. By default, a custom script will be executed on all supported platforms. oHPUX: The script will only be executed on HP-UX. oAIX: The script will only be executed on AIX. omacOS: The script will only be executed on macOS. oSolaris: The script will only be executed on Solaris. oLinux: The script will only be executed on Linux. oAll: The script will be executed on all supported platforms. |
•Command •Item •ForeachLine |
Example:
<CustomScript Name="SimpelName">
<Command Name[...]>
<Item Name[...]>
<ForeachLine Values[...]>
</CustomScript>
The command which is going to be executed on the target machine. The output of the executed command will be stored in the variable defined in the Name parameter.
Attributes |
Elements |
|---|---|
•Name: The name of the command. It can be used as a varialbe in ForeachLine sections, the Item section and in Properties. •OnError (optional): Is used to define how to treat errors. By default, the Ignore value will be used. oFail: If the command fails, the whole script will fail and not be processed anymore (if there are more than one script, the next script will be executed). oWarn: If the command fails, there is a notification in the log that the script has failed, but the next command/step will be executed. oIgnore: If the command fails, there will not be any log entry and the script will continue with the next command/step. •Text: the command to be executed on the target machine (needs to be formatted according to XML standard). |
•none |
Example:
<Command Name="CMD1" OnError="Warn">hostname</Command>
All commands and items defined in a ForeachLine will be executed multiple times depending on the number of lines in the input variable set in the parameter Values. The ForeachLine section needs to contain exactly one item section.
Attributes |
Elements |
|---|---|
•Values: The input variable. This variable has to be defined by a command previously in the script. The number of times the ForeachLine will be executed depends on the number of lines in this variable. •Name: During the processing of a ForeachLine script, each line from the input variable will be stored in the Name variable. One after each iteration. The sub commands and items will only see the currently parsed line. The variable and the defined value are exposed to the sub commands and sub item. |
•Command •Item |
Example:
<ForeachLine Values="$(CMD1)" Name="loop1">
<Command Name[...]>
<Item Name[...]>
</ForeachLine>
The actual inventory item that will be written into the inventory file. Each CustomScript can only have one item! If a CustomScript contains a ForeachLine, the CustomScript cannot contain an item section, as the ForeachLine section will already have one. Each inventory item that is added to the inventory file is stored as a Hardware item.
Attributes |
Elements |
|---|---|
•Name: The internally used name for thiks item. •Class: The class which will appear in the inventory file. •ItemName: The item name that will be stored as Name in the inventory item of the inventory file. |
•Property |
Example:
<Item Name="$(CMD1)" Class="MGS_ComputerSystem_Custom1" ItemName="$(CMD2)>
<Property Name[...]>
</Item>
This represents a property in the inventory file.
Attributes |
Elements |
|---|---|
•Name: The property name which will be set as name in the inventory file (does not accept variables). •Value: The value which will be set a s value in the inventory file. |
•none |
Example:
<Property Name="Hostname" Value="$(CMD1)"/>
The results of commands are stored in variables which can be accessed via the following syntax:
$(MyVariable)
It is further possible to treat a variable as an array (splitted by lines only) or as a two dimensional array (splitted by lines and whitespaces) - each array starts with zero.
Syntax to access one specific line of an array (will return the second line of the array):
$(MyVariable):1
Syntax to access one specific word of a two dimensional array (will return the third word of the second line of a variable):
$(MyVariable):1[2]
A single script for straight execution and the storage of multiple Commands:
<?xml version="1.0"?>
<CustomScriptSet Name="someName" Version="0.1.1">
<CustomScript Name="aSimpleExample">
<Command Name="cmd1" OnError="fail">uname -a</Command> <!-- If this fails, then the whole inventory fails. -->
<Command Name="cmd2" OnError="warn">hostname</Command> <!-- If this fails, a warning is logged (including CustomScriptSet.Name, ~Version, CustomScript.Name, Command content, output on stdout, on stderr and exitcode). -->
<Command Name="cmd3" OnError="ignore">dnsdomain</Command>
<Item Name=$(cmd2)" Class="MGS_ComputerSystem_Custom1" ItemName="$(cmd2)">
<Property Name="Hostname" Value="$(cmd2)"/> <!-- Just take the whole output of cmd2 for the value -->
<Property Name="Domain" Value="$(cmd3)"/>
<Property Name="Description" Value="$(cmd1)"/>
</Item>
</CustomScript>
</CustomScriptSet>
A single script accessing specific parts of the value of an variable (array):
<?xml version="1.0"?>
<CustomScriptSet Name="someName" Version="0.1.1">
<CustomScript Name="aMoreComplexExample" TargetPlatform="All">
<Command Name="cmd1" OnError="fail">uname -a</Command>
<Command Name="cmd2" OnError="warn">hostname</Command>
<Command Name="cmd3" OnError="ignore">dnsdomain</Command>
<Command Name="cmd4" OnError="warn">ls -la</Command>
<Item Name=$(cmd2)" Class="MGS_ComputerSystem_Custom2" ItemName="$(cmd2)">
<Property Name="Hostname" Value="$(cmd2)"/>
<Property Name="Domain" Value="$(cmd3)"/>
<Property Name="Description" Value="$(cmd1)"/>
<Property Name="ThirdLineOfOutput" Value="$(cmd4):2" OnError="ignore"/> <!-- zero-based index for lines, take the third line of cmd4 for Value -->
<Property Name="SecondWordInFourthLineOfOutput" Value="$(cmd4):2[1]" OnError="ignore"/> <!-- zero-based index for words, take the second word in the third line of output from cmd4 for Value -->
</Item>
</CustomScript>
</CustomScriptSet>
A single script using ForeachLines to process multiple line results of a Command:
<?xml version="1.0"?>
<CustomScriptSet Name="someName" Version="0.1.1">
<CustomScript Name="aLoopExample" TargetPlatform="Linux">
<Command Name="cmd1" OnError="fail">ip addr | egrep "^[0-9]+\:" | cut -d: -f2</Command>
<ForeachLine Values="$(cmd1)" Name="loop1">
<Command Name="cmd2" OnError="warn">ip addr show $(loop1)</Command>
<Item Name="$(loop1)" Class="MGS_NetworkAdapter_Custom2" ItemName="$(loop1)"> <!-- $(loop1) is just the current line passed in from Foreach for this line -->
<Property Name="IPAddress" Value="$(cmd2):2[1]"/>
<Property Name="MACAddress" Value="$(cmd2):1[1]"/>
</Item>
</ForeachLine>
</CustomScript>
</CustomScriptSet>