You are here: Using the Configurator > Running Scripts with the Configurator/RCS

# Running Scripts with the Configurator

Intel SCS include options that you can use to run scripts. These scripts can be batch files or executables created using scripting languages. Before the script starts to run, the Configurator sends parameter values about the Intel AMT system to the script. The script can then use these parameter values. For example, you could use a script to send data to your management console about each Intel AMT system after it is configured.

Note:
The parameter values are sent as a string. Parameters without values are sent as empty strings. Each parameter value is separated by a space.

For more information, see:

Scripts Run by the Configurator

Scripts run by the Configurator are only run on Intel AMT systems that support host-based configuration (Intel AMT 6.2 and higher). The script must be put in a location that the Configurator can access from the Intel AMT system. The Configurator can run a script after configuration, reconfiguration, and maintenance operations done with these commands:

- ConfigAMT
- MaintainAMT

This table describes the CLI parameters of these commands used to run scripts.

Parameter | Description
--- | ---
/FileToRun <filename> | If this parameter is supplied, the Configurator will run this executable file (batch, script, or executable) after the command has completed. If the /FileToRun parameter is used without the /LowSecurity global option, the file must be digitally signed (see Digital Signing of Files). If the file is not signed, the Configurator will NOT run the CLI command or the file. In addition, if the /LowSecurity parameter is not used, the file must be located in the same folder as the ACUConfig.exe file.
These additional optional parameters are valid only if /FileToRun was specified:
/FileHash <SHA256 hash> | When this parameter is supplied, the Configurator runs a hash function on the file supplied in the /FileToRun parameter. The result of the hash function is then compared with the original hash value of the file, supplied in this parameter. If the values of the hashes are different, the Configurator will NOT run the CLI command or the file. (If any change was made to the file, the hash values will not be the same.) Before you can use this option, you must generate a SHA256 hash value from the <filename> file. The sample_files folder includes an application (SHA256.exe) that you can use to generate the hash value. For example: SHA256.exe MyFile.bat will return the hash value of MyFile.bat. The hash value is marked in blue. Copy the value and supply it in the <SHA256 hash> parameter.
/FileUser <password> | It is recommended to use this parameter to supply a user with the minimum permissions required to run this file.
/FilePassword <password> | Contains the password required to run the file. Valid only if /FileUser was also specified.

This table describes the parameters and the sequence in which the Configurator sends them to the file that you specify in the /FileToRun parameter.

# | Description
--- | ---
1 | The user defined in the /FileUser parameter*
2 | The password defined in the /FilePassword parameter*
3 | The hostname defined in the Intel AMT device
4 | The FQDN defined in the Intel AMT device
5 | The UUID of the Intel AMT device
6 | The Intel MEBX password of the Intel AMT device*
7 | The password of the default Administrator (“admin”) user in the Intel AMT device*
String Example: fileusername fileuserpassword myhostname myhostname.example.com 88888888-8887-8888-8888-878888888888 mebxpassword adminpassword (Parameters marked with an asterisk (*) are sent to the script in Base64 format.)

What if a Failure Occurs?

Scripts defined to run after configuration, reconfiguration, maintenance, and unconfiguration operations only run if the operation is successful (or completes with warnings). By default, if the script fails, Intel SCS does not make any changes to the Intel AMT settings set by the operation that ran before the script. “Script failure” means that your script returned a non zero exit code, or Intel SCS did not succeed to run the script.

But leaving Intel AMT configured after a post configuration script fails might not be the result you want. If it is critical that your post configuration script will complete successfully, you might prefer to have Intel AMT unconfigured if the script fails.

For post configuration scripts run by the Configurator, you can define this using the /AbortOnFailure parameter. When this parameter is supplied, the Configurator will automatically unconfigure Intel AMT if the configuration operation fails or the post configuration script fails. But unconfiguration will only occur if the Intel AMT system was in an unconfigured state when the configuration operation started. The /AbortOnFailure parameter is ignored for reconfiguration and maintenance operations.

Script Runtime and Timeout

The maximum permitted runtime for scripts is 60 seconds. If the script does not complete within 60 seconds, the operation that was running when the script was called will return a warning. The warning is recorded in the log file and will contain an error code (0xC0003EAA) and a description like this:

“The supplied script has not finished in the time-out period defined by Intel® SCS”

Changing the maximum permitted runtime is not possible for scripts run by the Configurator. If your script requires more than 60 seconds to complete, you can wrap your script with a batch file like this:

Start Myscript.bat %1 %2 ...

Exit 0

This will cause the operation to return a success code (0). If you do this, your script will be responsible to handle any subsequent errors if they are generated by your script. Script errors will not be recorded in the log.

Parameters Sent in Base64 Format

Some of the parameters sent by the Configurator are sent in Base64 format.

The number of characters sent in the Base64 value representing the parameter must be divisible by 4. If it is not, additional “=” characters are added to the end of the Base64 value. For example, if the Base64 value includes only 6 characters two “=” characters are automatically added.

When Base64 values are sent to a batch file, the command line interpreter removes these additional “=” characters. This means that the parameter value cannot be decoded correctly. To solve this problem, add the missing “=” characters to the Base64 value before decoding it.