Orca Scripts Guide
Orca comes with several scripts to get you started collecting common configurations but probably doesn’t cover all of your needs. We designed Orca to be easily extensible so you can quickly add scripts to gather configuration data using your preferred scripting language.
Orca is designed to allow you to drop in scripts that you can also run directly at the command line. The built-in scripts provide some good examples. They’re written so that you can set the needed environment variables and run the script to debug it and validate the output data is what you want. Since you can specify the invocation shell, scripts can be written in virtually any language you want to use.
The following rules apply to all scripts used by Orca:
- Scripts must start with a shell specification line. This line will be stripped from the script before it is passed to the target server for execution.
- Exit status determines success or failure. An exit status of zero indicates to Orca that the data collection is considered successful. Any other value is treated as failure by Orca. If no configuration data is returned by the script, that will also be considered a failure.
- All output to the stdout and stderr handles is considered log data. Log data is made available in the Orca App on a per-server basis. Writing to stderr does not indicate that there has been an error. Log output is only available to the target owner.
- All configuration data output must be written to the file specified by the ORCA_PAYLOAD_FILE environment variable set by the agent for the script.
Shell Specification Line
Every script in Orca must start with a shell specification line. This line controls how the Orca Agent will run the script. It specifies the command/shell to invoke, the extension to use for the script filename on the local Filesystem (some interpreters require specific file extensions), and allows for a more complex command line to be used to invoke the script.
The format for the shell specification line is as follows:
- #! – This is a fixed, required prefix and must be the first 2 characters of the script.
- [.ext] – This optional component allows you to specify the extension of the filename used to hold the script contents. If omitted the agent will not add an extension to the temporary file created.
- cmd – The remainder of the line specifies the command string to be invoked. The agent will attempt to exec the string specified. If the string contains a pair of percent signs (%%) they will be replaced with the absolute path to the temporary file that holds the script to execute. If the string does not contain a pair of percent signs, the absolute path to the file that contains the script is appended to the command string.
Some examples of shell specification lines:
- #![.ps1]powershell.exe -ExecutionPolicy Bypass -NoProfile -InputFormat None -File “%%”
- #!/bin/bash -c “export VAR=value ; command -e %% ; rm -rf /tmp/tmpdir”
Would result in the agent running:
- /bin/sh /tmp/orca123XYZ
- powershell.exe -ExecutionPolicy Bypass -NoProfile -InputFormat None -File “/tmp/orca123XYZ.ps1”
- /bin/bash -c “export VAR=value ; command -e /tmp/orca123XYZ ; rm -rf /tmp/tmpdir”
Parameters are collected by Orca in precedence order and the final list of parameters will be set in the environment for the script to be run. Orca will set the ORCA_PAYLOAD_FILE environment variable at script runtime. This variable is set by the Orca agent so if you try to change or override it the script will run but you won’t get any configuration data inventoried!
Credential parameters have slightly different specification syntax to allow for you to specify the username or password component of a stored credential. In this case the parameter value in the Orca Desktop App must match the name of a credential, and be suffixed by one of .username or .password:
USER_NAME = my-credential-name.username
USER_PASSWORD = my-credential-name.password
Configuration Data Output
As mentioned previously, all configuration data output must be written to the file specified by the ORCA_PAYLOAD_FILE environment variable. This is the only environment variable that will be set by the Orca Agent rather than from parameters you define in the Desktop App.
Your script is free to do whatever is needed to collect the configuration data from the system or from a remote source. There are specific requirements for the way the data is returned to orca, however. Reviewing the out-of-box interfaces provided by Orca will be a quick way to see a few examples of this flow.
Configuration data is communicated to Orca with a header, followed by the raw configuration data. The header specifies the format of the data that follows, and also how much data follows the header:
format-name size [prefix]
<raw config data>
The format name must be one of the format names outlined in the table below. The size value can be one of two different values:
- * — An asterisk indicates that the remainder of the output will be data of the specified format.
- NN — A numeric value indicates that a specific number of bytes of the specified data format follows the format specification line.
The optional prefix is a string that you specify to help categorize the data. The prefix value is stored with the config data and will be visible when a difference is detected, helping you further identify the original source of the data. The prefix string will be automatically pre-pended to every line of config data your script collects.
Orca config data is stored in a simple format consisting of a path and a value separated by an equal sign:
The path portion identifies where the config data came from, specifically. If a value came from an ini format file config data might be stored as:
The orca-data format specifies that the lines of output from your script will be in the above format and shouldn’t be altered. This is the raw standard Orca data format. Orca provides some handlers that help simplify config data collection by scripts. Refer to the list of valid data format names in the table below.
If you use the ‘*’ size specification in your config data format specification line, the remainder of the script’s output will be collected as configuration data. If you specify a byte count as the size, Orca will consume that specific amount of data as configuration data of the specified format. Using a specific byte count allows you to collect and transmit multiple sources and formats of data in a single script:
orca-data-xml 21876 my-config.xml
<21,876 bytes of XML data>
orca-data-xml 1340 my-certs.xml
<1,340 bytes of XML data>
orca-data-pairs * env-settings-for-app
<arbitrary amount of NAME=VALUE formatted lines>
The data a script collects does not have to come from the local system. You can use remote access to retrieve data from an external source (for example, a database server) to avoid having to install an agent on that remote source. Simply retrieve the data from the remote source, format it appropriately, and write it to the ORCA_PAYLOAD_FILE file.
Valid Data Format Names
Format name Script Output Config data output format orca-data-ini A raw dump of the ini file to be processed. Use the prefix to specify any filename information. orca-data-pairs Simple, non-pathed NAME=VALUE pairs like a dump of an environment. Use the prefix to help identify the source of the data. orca-data-policy A raw dump of Java style policy files. Use the prefix to specify a source filename or other location information. orca-data-property A raw dump of Java style property files. Use the prefix to specify a source filename or other location information. orca-data-xml A raw dump of an XML file. The XML content will be parsed into the list of XPATH like values. Use the prefix to specify any filename information. orca-data Pre-formatted PATH=VALUE configuration data. Use this when you want full control over the path and value structure. Orca will pass this data as-is into the data comparison engine (after pre-pending any prefix string).