ascd.conf reference

Configuration file for the Application Service Controller daemon (ascd). If you alter the ascd.conf file, restart the ascd for the changes to take effect.

Note: After you change a parameter value, verify existing instance group configurations to ensure that the change is applied.

Location

The file is installed with IBM® Spectrum Conductor at $EGO_CONFDIR/../../ascd/conf.

Parameters

ASC_AUDIT_LOG

Enables or disables audit logging for ascd events that are related to instance groups and application instances.

Syntax: ASC_AUDIT_LOG=ON |OFF

Default value: OFF

ASC_AUDIT_LOG_CEF

When logging is enabled for ascd functions (by setting ASC_AUDIT_LOG=ON), saves the audit logs in ArcSight CEF (Common Event Format) standard, which provides a specific level of detail for the logs so that they can be analyzed with ArcSight tools.

Syntax: ASC_AUDIT_LOG_CEF=ON|OFF

Default: OFF

ASC_AUDIT_LOG_CEF_HEADER

Controls the date information for CEF (Common Event Format) standard auditing logs. If ASC_AUDIT_LOG_CEF_HEADER=ON, the logs show dates; if ASC_AUDIT_LOG_CEF_HEADER=OFF, the logs hide dates.

Typically, you will want to see dates in your logs, so keep this value as the default: ASC_AUDIT_LOG_CEF_HEADER=ON. If you do set this parameter to ASC_AUDIT_LOG_CEF_HEADER=OFF, ensure you use it along with the ASC_AUDIT_LOG_CEF=ON setting.

Syntax: ASC_AUDIT_LOG_CEF_HEADER=ON|OFF

Default: ON

ASC_AUTO_DEPLOY_ON_NEW_HOST

Turns on automatic deployment when a new host joins resource groups.

Syntax: ASC_AUTO_DEPLOY_ON_NEW_HOST=ON|OFF

Default value: ON

ASC_AUTO_DEPLOY_ON_NEW_HOST_INTERVAL_MIN

Sets the interval (in minutes) for checking whether new hosts have joined a resource group for automatic deployment. The minimum value to check for new hosts in a resource group is 2.

Syntax: ASC_AUTO_DEPLOY_ON_NEW_HOST_INTERVAL_MIN=value

Valid Values: Values must be positive integers. Do not include a negative integer or decimal.

Default value: 2

ASC_AUTO_DEPLOY_TIMEOUT_SEC

Sets the timeout (in seconds) for automatic package deployments.

Syntax: ASC_AUTO_DEPLOY_TIMEOUT_SEC=value

Default value: -1 (to indicate that there is no timeout)

ASC_CMD_BLOCKING_TIMEOUT_MS

Sets the duration (in milliseconds) that the system waits for packages to be validated when you are registering a instance group or an application instance, after which duration the package validation times out. To improve the success of registering instance groups or application instances in a large cluster, you can increase the timeout value.

Syntax: ASC_CMD_BLOCKING_TIMEOUT_MS=value

Default value: 30000

ASC_CMD_BLOCKING_INTERVAL_MS

Sets the interval (in milliseconds) between checks for package validation when you are registering a instance group or an application instance. Set to -1 to use the default interval of 100 ms.

Syntax: ASC_CMD_BLOCKING_INTERVAL_MS=value

Default value: -1

ASC_DEPLOY_DEFAULT_TIMEOUT_SECS

Sets the maximum time (in seconds) that the egodeploy download command can take to download and install the package on each compute host, beyond which the package installation times out. By default, a timeout is not configured. This is a global action that is applied every time a instance group or an application instance is deployed.

Syntax: ASC_DEPLOY_DEFAULT_TIMEOUT_SECS=value

Default value: -1

ASC_DEPLOY_HOST_SUCCESS_THRESHOLD

Set the minimum number or percentage of hosts that need to deploy successfully in order for a instance group or an application instance to move to either the Ready state (deploy successfully) or the Deploy Error state (deploy failure). If set to a number, then that number of hosts must succeed. If set to a percentage, then that many hosts must succeed for the resource group.

If some hosts fail to deploy, these hosts are blocked, either:

when the service starts, in the case that the deployment happened when the application was stopped; or
immediately, in the case that the application is running.

If a previously failed host succeeds to deploy while the instance group or application instance is running, the hosts are unblocked. It is best practice to use a percentage since this parameter is applied to all deployments across all resource groups, which might be of different sizes.

Syntax: ASC_DEPLOY_HOST_SUCCESS_THRESHOLD=value_in_percentage

Default value: 100%

ASC_DEPLOY_PUSH_LIMIT

Sets the maximum number of concurrent hosts that are actively downloading and installing packages. This is a global action that is applied every time a instance group or an application instance is deployed. Enter a value of -1 to not set a push limit.

Syntax: ASC_DEPLOY_PUSH_LIMIT=value

Default value: -1

ASC_DEPLOY_VIEW_CACHE_TIMEOUT_MS

Sets the duration (in milliseconds) for validated packages to be cached. Set to -1 to disable this caching.

Syntax: ASC_DEPLOY_VIEW_CACHE_TIMEOUT_MS=value

Default value: 300000

ASC_ES_MONITOR_SLEEP_MS

The interval (in milliseconds) at which the Elasticsearch monitoring thread runs for a instance group.

Syntax: ASC_ES_MONITOR_SLEEP_MS=value

Default: 30000

ASC_MONITOR_SLEEP_MS

Sets the monitoring period for ascd. After the set period, ascd monitors the instance groups or application instances, service states, deployment, etc., and refreshes itself. In large clusters, consider tuning the monitoring period to a higher value.

Syntax: ASC_MONITOR_SLEEP_MS=value

Default value: 10000

ASC_REF_BASED_UNDEPLOY

Enables or disables reference-based undeployment. When enabled, packages are removed from a host only if no other instance group or application instance is using that same host, package, and execution user. If reference-based undeployment is disabled, undeployment happens regardless of whether other instance groups or application instances are using that same host, package, and execution user.

Syntax: ASC_REF_BASED_UNDEPLOY=ON|OFF

Default value: ON

ASC_RG_MONITOR_SLEEP_MS

Sets the interval (in milliseconds) to check how resource groups are handling automatic deployments.

Syntax: ASC_RG_MONITOR_SLEEP_MS=value

Default value: 30000

ASC_THREADPOOL_THREADS

The value is used to initialize all three thread pools in ascd. For example, if the value is set to 50, there will be three times that many threads running in ascd, so 150 total.

Syntax: ASC_THREADPOOL_THREADS=value

Default value: 10

ASCD_GPU_ENABLED

Enables or disables the creation of instance groups that use GPU resources for applications. You can only use GPUs with certain Spark versions. Spark versions not supported: 1.5.2.

With this parameter enabled, if you choose to allow GPUs to be allocated to executors when you are creating a instance group, GPU slots (in addition to CPU slots) are allocated to Spark executors in the instance group. To support GPU scheduling, ensure that you set up a resource group containing hosts with GPU resources.

Syntax: ASCD_GPU_ENABLED=ON|OFF

Default value: OFF

ASCD_SHARED_FS_DEPLOY

Indicates package deployment to the shared file system. In this case, packages are deployed only once for each resource group. For instances (instance groups, Anaconda distribution instances, and application instances) deployed to a shared file system, ensure that the hosts in each resource group run on the same operating system type: they must either be all Linux® machines or all Linux on POWER® machines. Also, note that when shared file system deployment is enabled, automatic package deployment is disabled.

If you install IBM Spectrum Conductor to a shared file system (that is, during installation, set environment variable SHARED_FS_INSTALL=YES), the system sets this parameter to ASCD_SHARED_FS_DEPLOY=ON.

If you install IBM Spectrum Conductor to a local environment, the system sets this parameter to ASCD_SHARED_FS_DEPLOY=OFF. However, you can enable all instance deployments (instance groups, Anaconda distribution instances, and application instances deployments) on a shared file system (with a local installation of IBM Spectrum Conductor). In this case, change this value to ASCD_SHARED_FS_DEPLOY=ON, as described in Installing IBM Spectrum Conductor to a local environment and deploying instances to a shared file system).

Syntax: ASCD_SHARED_FS_DEPLOY=ON

Default value: OFF

CA_CERT_KEYSTORE_PASSWD

The password that the certificate authority keystore requires, as defined in CA_CERT_KEYSTORE_PATH. This property is used to verify the server that you are communicating with.

Syntax: CA_CERT_KEYSTORE_PASSWD={aes}ANr2+3vBND5lpzCl4QWrolYXCy3OggZWgvuDsjD7c5vF

Default value: {aes}ANr2+3vBND5lpzCl4QWrolYXCy3OggZWgvuDsjD7c5vF

CA_CERT_KEYSTORE_PATH

The location of the certificate authority keystore. This property is used to verify the server that you are communicating with.

Syntax: CA_CERT_KEYSTORE_PATH=$EGO_TOP/security/caKeyStore.jks

Default value: $EGO_TOP/security/caKeyStore.jks

CA_CERT_PATH

The path to the certificate authority certificates. This property is used to verify the server that you are communicating with.

Syntax: CA_CERT_PATH=${EGO_TOP}/wlp/usr/shared/resources/security/cacert.pem

Default value: ${EGO_TOP}/wlp/usr/shared/resources/security/cacert.pem

CONDUCTOR_JUPYTER_DATA_VOL_ENVS_ENABLED

Controls whether environment variables can be used in data volume definitions when you enable Dockerized Jupyter notebooks for an instance group. Valid values are:

ON: Enables the use of dollar signs ($), open curly brackets ({), and closed curly brackets (}) to define environment variables (such as /scratch/dev/${SPARK_EGO_USER}) in your host path and container path definitions for data volumes.
OFF: Disables the use of environment variables in host path and container path definitions for data volumes.

Syntax: CONDUCTOR_JUPYTER_DATA_VOL_ENVS_ENABLED=OFF | ON

Default value: OFF

CONDUCTOR_NOTEBOOK_AUTH_ENABLED

Controls whether notebook users must use their credentials to access the notebook within a browser. Valid values are:

ON: Notebook users are prompted to log in when they launch the notebook in a browser.
OFF: Notebook users can launch the notebook in a browser without having to log in.

Syntax: CONDUCTOR_NOTEBOOK_AUTH_ENABLED=ON|OFF

Default value: ON

CONDUCTOR_JUPYTER_TERMINAL_ENABLED

Enables terminal access for all Jupyter notebooks. Value can be either ON or OFF. This parameter takes effect for instance groups created after the value is set. For existing instance groups, you must redeploy the instance group for the value to take effect.

Syntax: CONDUCTOR_JUPYTER_TERMINAL_ENABLED=ON|OFF

Default value: ON

CONDUCTOR_SPARK_AUTOSTART_NOTEBOOKS_WITH_INSTANCE_GROUP

Specifies whether notebooks associated with an instance group are to start automatically when the instance group is started. Valid values are:

ON: Notebooks in the instance group start when the instance group starts.
OFF: Notebooks in the instance group do not start when the instance group starts. Use this setting to prevent notebooks from taking up slots when they are not in use.
If CONDUCTOR_SPARK_AUTOSTART_NOTEBOOKS_WITH_INSTANCE_GROUP=OFF, you must manually start the notebook when required (see Starting notebooks in an instance group).

Syntax: CONDUCTOR_SPARK_AUTOSTART_NOTEBOOKS_WITH_INSTANCE_GROUP=ON|OFF

Default value: ON

CONDUCTOR_SPARK_DEFAULT_RECOVERY_DIR

Enables high availability for all instance groups and specifies the default recovery directory for each instance group in the cluster. With this parameter defined, the recovery state of each Spark master is stored in a subdirectory, which is identified by the UUID of the instance group.

The recovery directory that you specify must be a shared directory. If you use an existing shared directory, the execution user for each instance group must have read/write/execute (rwx) permissions for the directory. Also, the execution user for the Spark batch master service and the Spark notebook master service in each instance group must have read/write/execute (rwx) permission for this directory.

Note: If you specify this directory to a shared NFS directory, you must manually clean up data under this location when the instance group is removed.

You can optionally override the default recovery directory when you create a instance group.

Syntax: CONDUCTOR_SPARK_DEFAULT_RECOVERY_DIR=/path_to_recovery_directory

Default value: Not defined

CONDUCTOR_SPARK_DOCKER_NOTEBOOK_START_TIMEOUT_SEC

The amount of time in seconds within which the Docker service must start before the service timeouts and is restarted. Changing this value does not affect existing notebooks. It takes effect only when new notebooks are added to a instance group. Configure this parameter when you have slow machines with services that are taking longer than 280 seconds to start. You can increase the value, however it is recommended that the value is not set higher than 290 to avoid services staying in the ALLOCATING state and not starting.

Syntax: CONDUCTOR_SPARK_DOCKER_NOTEBOOK_START_TIMEOUT_SEC=value

Default value: 280

CONDUCTOR_SPARK_ENFORCE_SPARK_EGO_AUTH_MODE

Enforces cluster-level authentication settings to prevent users from changing the Enable authentication and authorization for the submission user setting when creating or modifying a instance group. Define this parameter for the Spark master to either authenticate and authorize the specified user or to trust all users who submit Spark applications to instance groups. Valid values are:

EGO_AUTH: Enforces that the Spark master authenticate and authorize the specified submission user.
EGO_TRUST: Disables authentication and enforces that the Spark master trust all specified submission users; no password is required.

Syntax: CONDUCTOR_SPARK_ENFORCE_SPARK_EGO_AUTH_MODE=EGO_AUTH | EGO_TRUST

Default value: Not defined

CONDUCTOR_SPARK_ENFORCE_ENCRYPTION

Enforces cluster-level encryption settings in the Spark version to prevent users from changing Encryption settings when creating or modifying a instance group. Valid values are:

WORKLOADANDSPARKUIS: Enforces that SSL be enabled for workload and Spark UIs (the Spark master UI, driver UI, and history service UI). This option corresponds to the spark.ssl.enabled=true setting in the Spark version.
WORKLOADONLY: Enforces that SSL be enabled only for workload, which corresponds to the spark.ssl.enabled=false, spark.ssl.ego.workload.enabled=true, and spark.ssl.ego.gui.enabled=false settings in the Spark version.
SPARKUISONLY: Enforces that SSL be enabled only for Spark UIs, which corresponds to the spark.ssl.enabled=false, spark.ssl.ego.workload.enabled=false, and spark.ssl.ego.gui.enabled=true settings in the Spark version.
DISABLE: Enforces that SSL be disabled, which corresponds to the spark.ssl.enabled=false, spark.ssl.ego.workload.enabled=false, and spark.ssl.ego.gui.enabled=false settings in the Spark version.

Syntax: CONDUCTOR_SPARK_ENFORCE_ENCRYPTION=WORKLOADANDSPARKUIS | WORKLOADONLY | SPARKUISONLY | DISABLE

Default value: Not defined

CONDUCTOR_SPARK_ENFORCE_NOTEBOOK_SSL

Enforce SSL settings for notebooks to prevent users from changing the SSL setting when creating or modifying a notebook in a instance group. Valid values are:

TRUE: Enforces a setting of true to enable SSL for notebooks.
FALSE: Enforces a setting of false to disable SSL for notebooks.

Syntax: CONDUCTOR_SPARK_ENFORCE_NOTEBOOK_SSL=TRUE | FALSE

Default value: Not defined

CONDUCTOR_SPARK_ENFORCE_SECURITY_SPARK_AUTH

Enforces authentication in the Spark version to prevent users from changing the setting when creating or modifying a instance group. Valid values are:

TRUE: Enforces a setting of true for the spark.authenticate parameter in the Spark version.
FALSE: Enforces a setting of false for the spark.authenticate parameter in the Spark version.

Syntax: CONDUCTOR_SPARK_ENFORCE_SECURITY_SPARK_AUTH=TRUE | FALSE

Default value: Not defined

CONDUCTOR_SPARK_IMPERSONATION_PERMITTED

Allows cluster administrators to control the use of impersonation at the instance group level. When set to ON, users can configure impersonation for a instance group during instance group creation. When set to OFF, the impersonation function is disabled entirely and cannot be configured for a instance group.

Note: If instance groups exist with impersonation enabled, and the cluster administrator changes the CONDUCTOR_SPARK_IMPERSONATION_PERMITTED parameter from ON to OFF; the cluster administrator must modify each instance group to disable impersonation.

Syntax: CONDUCTOR_SPARK_IMPERSONATION_PERMITTED=ON|OFF

Default value: ON

CONDUCTOR_SPARK_RESERVE_MGHOSTS

Prevents services other than the Spark master from running on management hosts.

When enabled, all non-Spark master services, such as drivers, executors, the shuffle service, and notebooks (for example, Zeppelin 0.7.0), run only on compute hosts. Only the Spark master services (for batch applications, notebooks, and history server) run on management hosts (by default, hosts in the ManagementHosts resource group).

Syntax: CONDUCTOR_SPARK_RESERVE_MGHOSTS=ON|OFF

Default value: OFF

CONDUCTOR_SPARK_SERVICES_START_TIMEOUT_SEC

The amount of time in seconds within which the Spark master and Spark history service must start before the services timeout and are restarted. Changing this value does not affect existing instance groups. This parameter applies only to non-dockerized Spark instance groups, and takes effect only when instance groups are registered. Configure this parameter when you have slow machines with services that are taking longer than 180 seconds to start. You can increase the value, however it is recommended that the value is not set higher than 290 to avoid services staying in the ALLOCATING state and not starting.

Syntax: CONDUCTOR_SPARK_SERVICES_START_TIMEOUT_SEC=value

Default value: 180

CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_ALGORITHM

For a scheduled batch application, specifies the algorithm that is used to encrypt the token for the scheduling user. The scheduling user token is maintained for all users who schedule batch applications. Valid values are AES and DESede. If you change this setting to DESede, update the CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_KEYSIZE parameter to use 112 or 168 bits.

Note: You can modify this parameter after installation but only before you start the cluster for the first time.

Syntax: CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_ALGORITHM=DESede

Default: AES

CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_KEYSIZE

For a scheduled batch application, specifies the key size that is used to encrypt the token for the scheduling user. The scheduling user token is maintained for all users who schedule batch applications.

Note: You can modify this parameter after installation but only before you start the cluster for the first time.

Valid values are as follows:

If CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_ALGORITHM=AES, set the key size to 128 (default), 192, or 256 bits.
If CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_ALGORITHM=DESede, set the key size to 112 or 168 bits. If you use these settings, update the CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_ALGORITHM parameter to use DESede.

Syntax: CONDUCTOR_SPARK_SCHEDULED_APP_CIPHER_KEYSIZE=value

Default: 128

CONDUCTOR_SPARK_SSL_ENABLED

Turns SSL on by default for new instance groups, and allows SSL for existing instance groups. When set to OFF, SSL for instance groups cannot be enabled.

Syntax: CONDUCTOR_SPARK_SSL_ENABLED=ON|OFF

Default value: OFF or ON. OFF if DISABLESSL=Y is set during installation or upgrading from a previous version of IBM Spectrum Conductor.

ON if DISABLESSL=N is set or DISABLESSL was not set during installation.

CONDUCTOR_SPARK_UI_REVERSEPROXY

The URL where your proxy is running. When this value is set, new instance groups are created with spark.ui.reverseProxy=true and spark.ui.reverseProxyUrl=the value of this parameter. Spark versions not supported: 1.5.2, 1.6.1, and 2.0.1.

Syntax: CONDUCTOR_SPARK_UI_REVERSEPROXY=https://proxy.url:8443/path/to/spark/

Default value: Not defined

SPARK_EGO_LOG_OTHER_READABLE_ENABLED

Shows the Spark on EGO parameter, called SPARK_EGO_LOG_OTHER_READABLE, on the Spark configuration dialog when creating an instance group using the cluster management console.

To enable others the ability to read Spark driver, executor, and application event logs:

In the ascd.conf configuration file, set SPARK_EGO_LOG_OTHER_READABLE=ON, so that SPARK_EGO_LOG_OTHER_READABLE is visible as a Spark on EGO parameter on the Spark configuration dialog.
In the Spark configuration dialog, select Spark on EGO from the parameters list, and type OTHER the field beside it to list the SPARK_EGO_LOG_OTHER_READABLE parameter.
Set the SPARK_EGO_LOG_OTHER_READABLE parameter to true and click Save.

Syntax: SPARK_EGO_LOG_OTHER_READABLE_ENABLED=ON|OFF

Default value: OFF