Enabling and configuring Automation Action Script sensor

Prerequisites

Before you enable this sensor, complete the following steps:

1. Review the information in Securely using the automation framework.
2. If the sensor is used in a self-hosted (on-premises) environment, ensure that the automation feature flag is enabled.

Enabling the sensor

By default, the sensor is disabled. To enable the sensor, update the agent configuration file as shown in the following example:

com.instana.plugin.action.script:
  enabled: true # by default is false

Configuring script execution home

By default, the Action Script sensor creates and runs the scripts from the agent default temporary directory *instanaAgentDir*/data/tmp. To change this location, add the scriptExecutionHome attributes to the script sensor configuration in the agent configuration file. The scriptExecutionHome value must not contain any space character. If the default temporary directory for the agent *instanaAgentDir*/data/tmp contains any space character, you must specify a value for scriptExecutionHome.

com.instana.plugin.action.script:
  enabled: true
  scriptExecutionHome: '/myExecutionDir' # The path used for action script executions.

Configuring runAs

By default, the Action Script sensor runs the scripts as the user who started the Instana agent. On the Linux, AIX, and Solaris operating systems, the action scripts cannot run as root. Similarly, on Windows, the action scripts cannot run as Administrator. To configure the Action Script sensor to run the action scripts with alternative credentials, add the runAs and scriptExecutionHome attributes to the script sensor configuration in the agent configuration file. The runAs user requires read, write, and execute permissions in the scriptExecutionHome directory. For Windows, you also need to specify the password for the runAs user in the runAsUserPassword attribute. Use the vault for runAsUserPassword as shown in the following YAML configuration. Before you decide on a username for runAs user, review the information in Creating a dedicated user for script actions.

com.instana.plugin.action.script:
  enabled: true
  runAs: 'aUser'
  scriptExecutionHome: '/myExecutionDir' # The path used for action script executions.
  runAsUserPassword: # Required on Windows operating system.
    configuration_from:
      type: vault
      secret_key:
        path: <secret_path>
        key: <secret_key>

Configuring maximum concurrent actions

By default, the script sensor runs maximum of 10 concurrent script actions. If you want to change the maximum number of concurrent script actions, add the maxConcurrentActions attribute to the script sensor configuration section in the agent configuration file as follows:

com.instana.plugin.action.script:
  enabled: true
  maxConcurrentActions: 5  # optional, default value is 10

Configuring script default timeout

When you create a script action, you can set the maximum time in seconds to wait for the script action to complete. If you do not set the script action timeout during script action creation, then by default, a script action times out after 300 seconds. If you want to change this default timeout for action script execution, add the defaultTimeout attribute to the script sensor configuration section in the agent configuration file as follows:

com.instana.plugin.action.script:
  enabled: true
  defaultTimeout: 600 # optional, default timeout is 300 seconds

Configuring chroot

chroot is used to create a limited sandbox for the action script to run in. Therefore, the script cannot maliciously change data outside the scriptExecutionHome directory tree. Action Script support for chroot is available for agents that run on the AIX, Linux, and Solaris operating systems. When chroot is enabled, scriptExecutionHome is used as the root directory for the action script process. You must copy to the scriptExecutionHome directory all the system commands, interpreters, binaries, libraries and executables that are required for action script invocation. At minimum, you must copy su command used internally by the sensor to substitute the user. To enable the chroot for action script, update the agent configuration file as shown in the following example:

com.instana.plugin.action.script:
  enabled: true
  chrootEnabled: true # by default, chroot support is disabled
  scriptExecutionHome: '/home/test' # The path used for action script executions

Integrating a secret manager

If the script action in your action catalog uses Vault parameters, you must integrate the host agent with a secret manager.

Special considerations for running script actions on Windows

When you execute the script actions on Windows operating systems, you must consider the following prerequisites and restrictions.