twsinst

Before you begin

Ensure that you have the required authorization requirements, as described in Authorization roles for running the twsinst script.

About this task

During the installation process, if you do not specify the installation directory in the command, the twsinst script creates the files for each of the installation steps in the following directories:
On Windows™ operating systems
%ProgramFiles%\HCL\TWA_TWS_USER
On UNIX™ and Linux™ operating systems
/opt/HCL/TWA_TWS_USER
Where TWS_USER is the user for which you are installing the HCL Workload Automation instance that you specify in the command.

If you stop and restart the installation, the installation process starts from the installation step where it was stopped.

To install the z-centric agent, perform the following steps:

On Windows™ operating systems
  1. Download the HCL Workload Automation Agent eImage related to your operating system.
  2. Log in as administrator on the workstation where you want to install the product.
  3. In the image_directory\TWS\operating_system\ACTIONTOOLS directory, delete the .distributed file and create an empty file named .zcentric
  4. From image_directory\TWS\operating_system, run twsinst using the syntax described in the following section.
    Note: twsinst for Windows™ operating systems is a Visual Basic Script (VBS) that you can run in CScript and WScript mode.
    The HCL Workload Automation for Z user is automatically created. The software is installed by default in the HCL Workload Automation for Z installation directory. The default value is %ProgramFiles%\HCL\TWA.
On UNIX™ and Linux™ operating systems
  1. Download the HCL Workload Automation Agent eImage related to your operating system.
  2. Create the HCL Workload Automation for Z user. The software is installed by default in the user's home directory, referred to as /installation_dir/TWS
    User:
    TWS_user
    Home:
    /installation_dir/TWS (for example: /home/user1/TWS where user1 is the name of the HCL Workload Automation for Z user.)
  3. Log in as root on the workstation where you want to install the product.
  4. In the image_directory/TWS/operating_system/ACTIONTOOLS directory, delete the .distributed file and create an empty file named .zcentric
  5. From the image_directory/TWS/operating_system directory, run twsinst using the syntax described in the following section.

A successful installation by using the twsinst script issues the return code RC = 0. If the installation fails, see Analyzing return codes for agent installation, upgrade, restore, and uninstallation to understand the cause of the error.

Synopsis

On Windows™ operating systems
Show command usage and version
twsinst.vbs -u | -v
Install a new instance
twsinst.vbs -new -uname user_name
    -password user_password
    -agent zcentric
    [-agentid agent_id]  
    [-displayname agent_name]
    [-addjruntime true|false]
    [-displayname agent_name]
    [-domain user_domain]
    [-gateway local|remote|none]
    [-gwid gateway_id]
    [-hostname hostname]
    [-inst_dir install_directory]
    [-jmport port_number]
    [-jmportssl true|false]
    [-lang lang_id]
    -sslkeysfolder
    -sslpassword
    [-skip_usercheck]
    [-stoponcheckprereq]
    [-tdwbhostname hostname]
    [-tdwbport tdwbport_number]
    [-work_dir working_directory]
    [-zhostname zconn_hostname
    [-zport zconn_portnumber]
On UNIX™ and Linux™ operating systems
Show command usage and version
twsinst -u | -v
Install a new instance
twsinst -new -uname user_name
    -agent zcentric
    [-addjruntime true|false]
    [-agentid agent_id]  
    [-displayname agent_name] 
    [-gateway local|remote|none] 
    [-gwid gateway_id]
    [-hostname hostname]
    [-inst_dir install_directory]
    [-jmport port_number]
    [-jmportssl true|false]
    [-lang lang_id]  
    [-reset_perm]
    -sslkeysfolder
    -sslpassword
    [-skip_usercheck]
    [-stoponcheckprereq]
    [-tdwbhostname hostname]
    [-tdwbport tdwbport_number ]
    [-work_dir working_directory]
    [-zhostname zconn_hostname
    [-zport zconn_portnumber]

Parameters

-agent zcentric
Installs the HCL Workload Automation Agent (z-centric agent).
-addjruntime true|false

Adds the Java™ run time to run job types with advanced options, both those types that are supplied with the product and the additional types that are implemented through the custom plug-ins. Valid values are true and false. The default for a fresh installation is true. Set this parameter to true if you use the sslkeysfolder and sslpassword parameters to define custom certificates in PEM format.

-agentid agent_id
A unique identifier for the z-centric agent, made up of exactly 32 characters. If not provided, an alphanumeric ID is automatically generated, as in the following example:
893164748CCA4FC6820F12685AECBB07

To reuse an agent ID for reinstallations, specify the same agent_id. Ensure that the value is 32 characters long, otherwise an error occurs.

This parameter is registered in the JobManager.ini file and is used to define the GATEWAY destinations in the HTTP or HTTPS parameter of the ROUTOPTS statement.

-domain user_domain
Windows™ operating systems only. The domain name of the HCL Workload Automation user. The default is the name of the workstation on which you are installing the z-centric agent.
-displayname agent_name
The name to be assigned to the z-centric agent. The default is the host name.
-gateway local|remote|none
Specifies whether to configure a gateway to connect the z-centric agent to the Z controller. You can set the following values:
local
The gateway resides in the z-centric agent workstation that you are installing.
remote
The z-centric agent communicates through a gateway that is configured on a different z-centric agent workstation.
None
No gateway is configured. This is the default value.
For information about installing the z-centric agent with a local or remote gateway, see z-Centric agent gateway installation examples.
-gwid gateway_id
The unique identifier for the gateway. This parameter is required when you specify -gateway local and must be unique across all z-centric agents. The default gateway identifier that is assigned is GW1. The gateway identifier must start with either an alphabetic character or an underscore character (_), and it can contain only the following types of characters: alphabetic, numeric, underscores (_), hyphens (-), and periods (.).

Gateways can also work in parallel to mutually take over in routing communications to the agents connected to them. To enable gateways to work in parallel, all gateways must have the same gateway_id assigned. This information is stored in the JobManagerGW.ini file by setting the JobManagerGWURIs property.

-hostname hostname
The fully qualified host name or IP address on which the agent will be contacted by the dynamic workload broker.
-inst_dir install_directory
The directory where to install the HCL Workload Automation Agent. On UNIX™ and Linux™, this path cannot contain blanks. On Windows™ operating systems, if you specify a path that contains blanks, enclose it in double quotes. On any operating system, specify an absolute path. If you do not manually specify a path, the path is set to the default home directory. On UNIX™ and Linux™, the path is set to the user_name home directory, and on Windows™ operating systems it is set to .
-jmport port_number

The port used by the Z controller or dynamic workload broker to connect to the z-centric agent. The valid range is from 1 to 65535. The default value is 31114.

-jmportssl true|false
The port used by the Z controller or dynamic workload broker to connect to the z-centric agent. This number is registered in the ita.ini file, located in ITA\cpa\ita on Windows™ operating systems and ITA/cpa/ita on UNIX™ and Linux™.
For communication using SSL or HTTPS
Set jmportssl = true. To communicate with the dynamic workload broker, it is recommended that you set the value to true. In this case, the port specified in jmport communicates in HTTPS. If you specify true, ensure that you also configure the HTTPS communication on the z/OS® master.
For communication without using SSL, or through HTTP
Set jmportssl = false. In this case the port specified in jmport communicates in HTTP.
The default value is true.

To increase the performance of the HCL Workload Automation for Z server, it is recommended that you set this value to false.

-lang lang_id
The language in which the twsinst messages are displayed. If not specified, the system LANG is used. If the related catalog is missing, the default C language catalog is used.
Note: This is the language in which the installation log is recorded, and not the language of the installed engine instance. twsinst installs all languages as default.
-new
A fresh installation of the agent. Installs an agent and all supported language packs.
-password user_password
Windows™ operating systems only. The password of the user for which you are installing HCL Workload Automation Agent. The password can include alphanumeric, dash (-), and underscore (_) characters, and the following symbols: ()!?=ˆ*/˜ [] $`+;:.,@.
-reset_perm
UNIX™ and Linux™ only. Reset the permissions of the libatrc library.
-skip_usercheck
Enable this option if the authentication process within your organization is not standard, thereby disabling the default authentication option. On UNIX™ and Linux™ operating systems if you specify this parameter, the program skips the check of the user in the /etc/passwd file or the check you perform using the su command. On Windows™ operating systems if you specify this parameter, the program does not create the user you specified in the uname username parameter. If you specify this parameter you must create the user manually before running the script.
-sslkeysfolder path
The name and path of the folder on the agent containing PEM certificates. The installation program automatically generates the keystore and truststore files using the password you specify with the sslpassword parameter, which is required when using sslkeysfolder.

The folder must contain the following files and folders:

ca.crt
The Certificate Authority (CA) public certificate.
tls.key
The private key for the instance to be installed.
tls.crt
The public part of the previous key.
tls.sth
The file storing your encoded password in Base64 encoding.

You can optionally create a subfolder to contain one or more *.crt files to be added to the server truststore as trusted CA. This can be used for example to add to the list of trusted CAs the certificate of the LDAP server or DB2 server. Additionally, you can store here any intermediate CA certificate to be added to the truststore. The subfolder must be named additionalCAs. If you are connecting a master domain manager using custom certificates to a dynamic agent also using custom certificates, the only required file is ca.crt.

Before you start the installation, ensure the required files and folders are available on the agent.

The sslkeysfolder and sslpassword parameters are mutually exclusive with the wauser, wapassword, apikey, and jwt true parameters, which are used to download and deploy the certificates or JWT already available on the master domain manager.

For a comprehensive list of supported combinations for this parameter and related ones, see #custlersz__d1171e2024.
-sslpassword password
Specify the password for the certificates in PEM format automatically generated by the installation program. It requires the sslkeysfolder parameter.

If you use this parameter, ensure that the addjruntime parameter is set to true, because Java™ run time is required for defining custom certificates.

You can optionally encrypt the password by using the secure script. For more information, see Encrypting passwords (optional).
-stoponcheckprereq
Stop the installation whenever a problem occurs during the prerequisite check. For more information about the prerequisites, see Product Requirements.
-tdwbhostname hostname
The fully qualified host name or IP address of the Z controller to which the z-centric agent is registering. If you set this parameter, you must also set the tdwbport parameter.

This parameter is required if the gateway parameter is set to remote or local. If gateway is set to remote, this is the host name of the z-centric agent hosting the gateway and to which the agent that you are installing will connect. This information is stored in theJobManager.ini file.

For example scenarios about installing with a local or remote gateway, see z-Centric agent gateway installation examples.

-tdwbport tdwbport_number
The port number of the Z controller to which the z-centric agent is registering. It must be coincident with the port that you specified in either the HTTPPORTNUMBER or SSLPORT parameter of the HTTPOPTS statement. This parameter is required if you set the tdwbhostname parameter.

If you set the gateway parameter to remote, this is the HTTP or HTTPS port set in the jmport parameter of the z-centric agent hosting the gateway and to which the agent that you are installing will connect.

For information about installing the z-centric agent with a local or remote gateway, see z-Centric agent gateway installation examples

-u
Displays command usage information and exits.
-uname user_name
The name of the user for which the z-centric agent is installed. This user name is not to be confused with the user performing the installation logged on as root on UNIX™ and Linux™ and as administrator on Windows™ operating systems.

On UNIX™ and Linux™, this user account must be created manually before running the installation. Create a user with a home directory. By default, z-centric agent is installed in the home directory of the specified user.

-work_dir working_directory
The temporary directory used for the HCL Workload Automation installation process files deployment.
On Windows™ operating systems
If you specify a path that contains blanks, enclose it in double quotes. If you do not manually specify a path, the path is set to %temp%\TWA\tws95, where %temp% is the temporary directory of the operating system.
On UNIX™ and Linux™ operating systems
The path cannot contain blanks. If you do not manually specify a path, the path is set to /tmp/TWA/tws95.
-v
Displays the command version and exits.
-zhostname zconn_hostname
The fully qualified host name of the Z connector (this is coincident with the Dynamic Workload Console host name). It is used together with the -zport zconn_port parameter. It adds the capability to download the plug-ins from the Z connector.

This value is registered in the ResourceAdvisorAgent property of the JobManager.ini file.

-zport zconn_portnumber
The HTTP or HTTPS port number of the Z connector (this is coincident with the Dynamic Workload Console port number). It is used together with the -zhostname zconn_hostname parameter to add the capability to download the plug-ins from the Z connector. The valid range is from 1 to 65535.

This value is registered in the ResourceAdvisorAgent property in the JobManager.ini file.

Examples

This example describes how to install the z-centric agent for the user HWA_user and accept the default value to add the runtime environment for Java™. The runtime environment is used to run jobs supplied with the product or implemented through the custom plug-ins, it also enables the capability to remotely run, from the agent, the dynamic workload broker resource command on the server.
On Windows™ operating systems
twsinst.vbs -new
-uname HWA_user
-password qaz12qaz
-jmportssl false
-jmport 31114 
-inst_dir "install_directory"
-sslkeysfolder certs_path
-sslpassword pwd
On UNIX™ and Linux™ operating systems
./twsinst -new
-uname HWA_user
-jmportssl false
-jmport 31114
-inst_dir install_directory
-sslkeysfolder certs_path
-sslpassword pwd