Agent installation parameters - twsinst script
Agent installation parameters that can be passed to the twsinst script.
This section lists and describes the parameters that are used when running a twsinst script to install the fault-tolerant or dynamic agent.
To see some sample agent installation scenarios see Example installation commands and Dynamic agent gateway installation examples.
JAVA_HOME=path_to_JAVA;export JAVA_HOME; twsinst_directory/twsinst
This
is because Java on these operating systems is not installed with IBM® Workload
Scheduler.- -acceptlicense yes|no
- Specify whether to accept the License Agreement.
- -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.
This option is applicable to both fault-tolerant agents and dynamic agents.
Note: Only for version 10.1 and subsequent fix packs, the addjruntime parameter is ignored and Java runtime is always installed automatically. - -agent dynamic|fta|both
- The type of agent that you want to install. Valid values are:
- dynamic
- To install the IBM Workload Scheduler dynamic
agent. Use this value with the -tdwbhostname
host_name and the -tdwbport
tdwbport_number parameters.
On Windows operating systems, you can install dynamic agents using the Local System Account. To install with the Local System Account, omit the uname and password parameters.
- fta
- To install the IBM Workload Scheduler fault-tolerant agent.
- both
- To install the dynamic agent that is used with the -tdwbhostname host_name and the -tdwbport tdwbport_number parameters, and a fault-tolerant agent.
- -agentid agent_id
- The unique identifier of the agent that you want to install. The parameter is optional. If not
specified, the installation process assigns to the agent a string of alphanumeric
characters, as in the following example:
It might be useful to specify an agent_id when you want to reinstall an agent after it was uninstalled, and you want to use the same agent_id. This prevents that two different agent_id values are registered on the server for the same agent installation.893164748CCA4FC6820F12685AECBB07
Note: When you manually specify the agent_id value, ensure that the length is 32 characters, otherwise an error occurs. - -apikey
- Use this parameter to specify the API key to be used for authenticating with the master domain manager. This authentication enables downloading the certificates or JWT to be used for communication between dynamic agent and dynamic domain manager. This parameter is mutually exclusive with the wauser and wapassword parameters. Obtain the string to be provided with this parameter from the Dynamic Workload Console before running the command. For more information, see Authenticating the command line client using API Keys.
- -company company_name
- The name of the company. The company name cannot contain blank characters. The name is shown in program headers and reports. If not specified, the default name is COMPANY.
- -create_link
- UNIX™ systems only. Create the symlink between /usr/bin/at and install_dir/TWS/bin/at. For more information, see Table 1.
- -data_dir path
- This argument applies to UNIX operating systems only. Specify a path for product data, such as log and configuration files, if you want to install the product binaries separated from the product data. This argument is optional. The default value is INSTALL_DIR/TWSDATA.
- -displayname display_name
- The name to assign
to the agent. The name cannot start with a number. The default is the host name of this
computer.
If the host name starts with a number, the -displayname parameter must be specified.
- -domain user_domain
- Windows™ systems only. The domain name of the IBM Workload Scheduler user. The default is the name of the workstation on which you are installing the product. Ensure you use USERDOMAIN instead of USERDNSDOMAIN.
- -encryptionpassword default
- The password for the keystore storing the AES-256 or AES-128 keys used to encrypt the files at runtime. This parameter is optional. The default value is default. You can optionally encrypt the password using the secure script. For more information, see Optional password encryption - secure script.
- -gateway local|remote|none
- Specifies whether to configure a gateway to communicate with the dynamic workload broker or not, and how it is configured. Specify local if the gateway is local to the dynamic agent workstation. Specify remote if the dynamic agent communicates through a gateway that is installed on a different dynamic agent workstation from the dynamic agent being installed. The default value is none, which means no gateway is configured. For information about installing with a local and remote gateway, see Example installation commands.
- -gweifport gateway_eif_port
- Specifies the Job Manager Event Integration Facility (EIF) port number. The default value is 31132. The valid range is 1 to 65535.
- -gwid gateway_id
- The unique identifier for the gateway. This parameter is required when you specify
-gateway
local. 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 host_name
- The fully qualified hostname or IP address on which the agent is contacted by the dynamic workload broker. The default is the hostname of this computer. If the hostname is a localhost, the hostname parameter must be specified.
- -inst_dir installation_dir
- The directory of the IBM Workload Scheduler installation.
On Windows operating systems:
- If you specify a path that contains blanks, enclose it in double quotation marks. Specify an absolute path. If you do not manually specify a path, the path is set to %ProgramFiles%\IBM\TWA_TWS_USER, where TWS_USER is the user for which you are installing the IBM Workload Scheduler that you specify in the -uname parameter. If you use the Local System Account and therefore do not specify the -uname parameter, the path is set to %ProgramFiles%\IBM\TWA_WaLocalSystemAccount.
On UNIX and Linux™ operating systems:
- If you specify a path that contains blanks, enclose it in double
quotation marks. Specify an absolute path.
If you do not manually specify a path, the path is set to:
- /opt/IBM/TWA_TWS_USER, if you logged in as the root user to install the agent. TWS_USER is the user that you specify in the -uname option and for which you are installing the agent (can omit if TWS_USER is root). The IBM Workload Scheduler user that you specify in the -uname username parameter must have read and run privileges for the installation_dir installation path; otherwise the installation fails.
- home_dir/TWA, if you logged in with a login other than root. Ensure that the directory permission is set to 755 for home_dir, the home directory for your login, and that you are the home_dir owner.
- -jmport port_number
-
The JobManager port number used by the dynamic workload broker to connect to the dynamic agent. The default value is 31114. The valid range is from 1 to 65535.
- -jmportssl true|false
- The JobManager port used by the dynamic workload broker to connect to the
IBM Workload Scheduler
dynamic agent. The
port value is the value of the ssl_port parameter in the ita.ini
file if -jmportssl is set to true. If set to
false, it corresponds to the value of the
tcp_port parameter in the ita.ini file. The
ita.ini file is located in ITA\cpa\ita on
Windows systems and
ITA/cpa/ita on UNIX, Linux, and IBM i systems.
Set the value to "true" if - gateway is set to local.
- 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.
- For communication without using SSL or through HTTP
- Set jmportssl = false. In this case the port specified in jmport communicates in HTTP.
- -jwt true | false
-
Specify true to use the JSON Web Token (JWT) to authenticate with the master domain manager. Specify false to authenticate with the master domain manager using certificates. The default value is true. This parameter is mutually exclusive with the sslkeysfolder and sslpassword parameters which are used to generate custom certificates.
- -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. If neither -lang nor LANG are used, the default
codepage is set to SBCS. For a list of valid values for these variables, see the
following table:
Table 1. Valid values for -lang and LANG parameter Language Value Brazilian portuguese pt_BR Chinese (traditional and simplified) zh_CN, zh_TW English en French fr German de Italian it Japanese ja Korean ko Russian ru Spanish es 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. - -master workstation
- The workstation name of the master domain manager. This name cannot exceed 16 characters, cannot contain spaces, and cannot be the same as the workstation name that you entered in the thiscpu parameter. If not specified, the default value is MASTER.
- -new
- A fresh installation of the agent. Installs an agent and all supported language packs.
- -password user_password
- Windows systems only. The password of the user for
which you are installing IBM Workload Scheduler.
The password can include alphanumeric, dash (-), and
underscore (_) characters, and the following symbols: ()!?=ˆ*/˜ []
$`+;:.@. The -password parameter is used for fresh
installations only, it is not required for fix packs or upgrades. You can optionally encrypt the password using the secure script. For more
information, see Optional password encryption - secure script.
On Windows operating systems, you can install dynamic agents using the Local System Account. To install with the Local System Account, omit the uname and password parameters.
- -netmansslport SSL_port_number
- The TCP/IP port number used by the netman process to listen for communication from the master in SSL mode. The default value is 31113. The valid range is from 1 to 65535. You can also set the netmansslport parameter to disabled to use non-encrypted communication. If you set the netmansslport parameter to disabled, you must provide a value for the netmanport parameter. This port number is registered in the localopts file, in the nm ssl full port attribute. For each installation you must specify a different number.
- -port port_number
- The TCP/IP port number used by the Netman process to listen for communication from the master. The default value is 31111. The valid range is from 1 to 65535. This port number is registered in the localopts file. For each installation you must specify a different number.You can also set this parameter to disabled. In this case, you must provide a value for the netmansslport parameter, which enables SSL communication.
- -reset_perm
- UNIX and IBM i systems only. Reset the permission of the libraries in the /usr/ibm directory.
- -restore
- Run this command from the folder to where you copied the eImage (a folder other than the home directory of TWS_USER, where TWS_USER is the user that installed the IBM Workload Scheduler instance), and not from the installation path, to restore the version in the eImage.
- -skip_usercheck
- Enable this option if the authentication process within your organization is not standard,
thereby disabling the default authentication option.
On Windows systems, if you specify this parameter, the program does not create the user you specified in the -uname username parameter and you must create the user manually before running the script. However, if you use Local System Account, you do not need to specify any user.
On UNIX and Linux 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.
- -skipcheckprereq
- If you specify this parameter, IBM Workload Scheduler does not scan system prerequisites before installing the agent. For more information on the prerequisite check, see Scanning system prerequisites for IBM Workload Scheduler.
- -sslkeysfolder path
- The name and path of the folder on the agent containing
certificates in .pem format. The installation program automatically
processes the keystore and truststore files using the password you specify with the
--sslpassword parameter. The folder must contain the following
files:
-
- 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.
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.
This parameter is required if you set the --dbsslconnection parameter to true.The sslkeysfolder and sslpassword parameters are mutually exclusive with the wauser, wapassword, and jwt parameters, which are used to download and deploy the certificates or JWT already available on the master domain manager.
-
- -sslpassword password
- The password for the custom certificates and the path to the folder containing certificates in .PEM format with the sslkeysfolder parameter. You can optionally encrypt the password using the secure script. For more information, see Optional password encryption - secure script.
- -tdwbhostname host_name
- The fully qualified host name or IP address of the dynamic workload broker the agent is
registering to. It applies when you set the -agent parameter to
either dynamic or both and requires the -tdwbport
parameter. If not specified, you cannot run your workload dynamically and this parameter
assumes the localhost default value.
If you set the -gateway parameter to remote, this is the host name of the dynamic agent hosting the gateway and to which the agent you are installing will connect. This information is stored in the JobManager.ini file. For information about installing with a local and remote gateway, see Example installation commands.
If you set the jwt parameter to true, ensure you provide a value for this parameter, so that you can download the JWT and agent ID from the specified dynamic domain manager. The dynamic domain manager routes the JWT request to the master domain manager. See also -jwt true | false. - -tdwbport tdwbport_number
- The HTTPS transport port number of the dynamic workload broker the
agent is registering to. It must match the port you specified with
httpsport parameter when installing the master domain manager. It applies when you set
the -agent parameter to either dynamic or both and
requires the -tdwbhostname parameter. The default value is
31116. The valid range is from 0 to 65535. If you specify
0 or do not specify this parameter, you cannot run workload
dynamically. Do not specify 0 if the -agent
value is dynamic or both. The default is
0 for an upgrade, which means that this connection is not
configured, otherwise, specify 31116 for a fresh installation.
If you set the -gateway parameter to remote, this is the HTTP or HTTPS port number of the dynamic agent hosting the gateway and to which the agent you are installing will connect. You have specified this port with the jmport parameter when installing the agent hosting the gateway. For information about installing with a local and remote gateway, see Example installation commands.
If you are performing a fresh installation, the value to use is 31114. This information is stored in the JobManager.ini file.
If you set the jwt parameter to true, ensure you provide a value for this parameter, so that you can download the JWT and agent ID from the specified dynamic domain manager. The dynamic domain manager routes the JWT request to the master domain manager. See also -jwt true | false. - -thiscpu workstation
- The name of the
IBM Workload Scheduler
workstation of this installation. The name cannot exceed 16 characters, cannot start
with a number, cannot contain spaces, and cannot be the same as the workstation name of
the master domain manager. This name is registered in the localopts
file. If not specified, the default value is the host name of the workstation.
If the host name starts with a number, -thiscpu parameter must be specified.
- -u
- Displays command usage information and exits.
- -uname username
- The name of the user for which the IBM Workload Scheduler agent is being
installed. This user owns the IBM Workload Scheduler instance and by
default, jobs are run with its name. This user name is not to be confused with the user
performing the installation. The user name cannot contain periods (.).
On UNIX and Linux systems, for a new installation, this user account must be created manually before running the installation and must be enabled to login to the machine where the agent is going to be installed. Create a user with a home directory. IBM Workload Scheduler is installed by default under the home directory of the specified user.
Dynamic agents can be installed on UNIX and Linux systems also by installers without root privileges. When this is the case:- username takes by default the login name of the installer and uname can be omitted. If uname is specified with a different value than the login of the installer, an error message is returned.
- As a consequence, the agent can run jobs uniquely with the user name of the installer.
- Event Management triggers on files work only if the selected files are accessible to the user that was used for the installation.
- The user must be enabled to login to the machine where the agent is going to be installed.
On Windows operating systems, you can install dynamic agents using the Local System Account. To install with the Local System Account, omit the uname and password parameters.
- -useencryption true | false
- Specifies whether IBM Workload Scheduler files must be encrypted at runtime. If you specify true, or do not set this parameter, files such as the Symphony file and the message queues are encrypted using AES-256 or AES-128 cryptography. By default, a fresh installation is automatically encrypted and the keystore password is default. To change the keystore password, use the encryptionpassword parameter. This parameter is optional.
- -wauser wauser_name
- One of the following users, defined on the
master domain manager:
- The user for which you have installed the master domain manager the agent is connecting to.
- The user with the DISPLAY permission on the FILE named AGENT_CERTIFICATE. This permission allows the user to download certificates or JWT. For more information about this scenario, see Downloading certificates or JWT using a different user.
- -wapassword wauser_password
- One of the following passwords, defined on the master domain manager:
- The password of the user for which you have installed the master domain manager the agent is connecting to.
- The password of the user with the DISPLAY permission on the FILE named AGENT_CERTIFICATE. This permission allows the user to download certificates or JWT. For more information about this scenario, see Downloading certificates or JWT using a different user.
- -work_dir working_dir
- The temporary directory used by the program to deploy the installation process files.
On Windows operating systems:
- If you specify a path that contains blanks, enclose it in double quotation
marks. If you do not manually specify a path, the path is set to
%temp%\TWA\twsversion_number, 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/twsversion_number.
- -v
- Displays the command version and exits.