Certificates download to dynamic agents - AgentCertificateDownloader script

This script downloads and deploys certificates in .PEM format from the master domain manager to dynamic agents or enables authentication through JSON Web Token (JWT).

You can use this script either to download and deploy certificates in .PEM format from the master domain manager to the dynamic agents in your environment or to enable authentication through JSON Web Token (JWT).

When installing the agent with a fresh installation, you only need to provide the credentials to connect to the master domain manager using the wauser and wapassword or the apikey parameters. The certificates in .PEM format are automatically downloaded and deployed to the agent without further intervention. The same happens if you are using JWT as authentication method.

When certificates are nearing their expiration time, new certificates are automatically downloaded to agents, but error conditions might happen, for example in case the agent is down or disconnected when the automatic certificate update takes place. In this case, you can use this command if you need to change the .PEM certificates after their expiration time, or if you have downloaded wrong .PEM certificates.

You can also use this command to obtain a new JWT for an agent from which you had previously revoked the JWT. Fore more information about revoking a JWT, see Revoking and reissuing a JSON Web Token.

If you authenticate using .PEM certificates, the script connects to the master domain manager to retrieve the compressed file containing the certificates, and saves them to the working directory with name waCertificates.zip.

Before running the command, ensure the certificates in .PEM format are available on the master domain manager in one of the following paths:
On Windows operating systems
installation_directory\TWS\ssl\depot
On UNIX operating systems
TWA_DATA_DIR/ssl/depot
The required files are:
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.

When running the command, you can type parameters and values from a properties file, type them in the command line, or use a combination of both properties file and command line. If a parameter is specified both in the properties file and in the command line, the command line value is used.

After running the command, stop and restart the agent process using the ShutDownLwa and StartUpLwa commands. For more information about the commands, see ShutDownLwa - Stop the agent and StartUpLwa - Start the agent.

Ensure you start the command from a brand-new shell.

Syntax

Certificate installation syntax on Windows operating systems
Show command usage
cscript AgentCertificateDownloader.vbs -? | --usage | --help
Retrieve the command parameters and values from a properties file
cscript AgentCertificateDownloader.vbs --file | -f  [properties_file]
General information

    cscript AgentCertificateDownloader.vbs
    [--wauser wauser_name]
    --wapassword wauser_password
    [--jwt true | false]
    [--apikey API_key_string]
    [--tdwbhostname host_name]
    [--tdwbport tdwbport_number]
    --work_dir working_dir
    [--gateway local | remote | none]
    [--gwid gateway_id]
Certificate installation syntax on UNIX operating systems
Show command usage
./AgentCertificateDownloader.sh --? | --usage | --help
Retrieve the command parameters and values from a properties file
./AgentCertificateDownloader.sh --file | --f  [properties_file]
General information

    ./AgentCertificateDownloader.sh
    [--wauser wauser_name]
    --wapassword wauser_password
    [--jwt true | false]
    [--tdwbhostname host_name]
    [--tdwbport tdwbport_number]
    --work_dir working_dir
    [--gateway local | remote | none]
    [--gwid gateway_id]

AgentCertificateDownloader parameters

--? | --usage | --help
Displays the command usage and exits.
--propfile | --f [properties_file]
Optionally specify a properties file containing custom values for AgentCertificateDownloader parameters. The default file is located in the root directory of the installation image.
Specifying a properties file is suggested if you have a high number of parameters which require custom values. You can also reuse the file with minimal modification for several installations. If you create a custom properties file, specify its name and path with the -f parameter.
General information
--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.
By providing the wauser and wapassword parameters or the apikey parameter, you enable HCL Workload Automation to download and install either the certificates in .PEM format or the JWT already available on the master domain manager. To download .PEM certificates, set the jwt parameter to false, to download JWT, set the jwt parameter to true.
--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.
Always specify the user defined on the master domain manager, also if you are installing a dynamic agent and want it to register to a dynamic domain manager. This is because the dynamic domain manager simply forwards data to and from the master domain manager.
By providing the wauser and wapassword parameters or the apikey parameter, you enable HCL Workload Automation to download and install either the certificates in .PEM format or the JWT already available on the master domain manager. To download .PEM certificates, set the jwt parameter to false, to download JWT, set the jwt parameter to true.
--jwt true | false
Specify true to download the JSON Web Token (JWT) to authenticate with the master domain manager. Specify false to download the certificates from the master domain manager and authenticate using the certificates. This parameter is mutually exclusive with the sslkeysfolder and sslpassword parameters which are used to generate custom certificates.
The default value is false, so that if you run this command .PEM certificates are downloaded instead of the JWT. This is because having to download the JWT is an unlikely scenario. If you set this parameter to true, the following parameters are required for downloading the JWT:
  • wauser or apikey
  • wapassword or apikey
  • tdwbhostname
  • tdwbport
-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.
--tdwbhostname host_name
The fully qualified host name or IP address of the broker server to which the agent is connected. The default value is localhost. If you set the jwt parameter to true, ensure you provide a value for this parameter, to download the JWT and agent ID from the dynamic domain manager. The dynamic domain manager routes the JWT request to the master domain manager.
--tdwbport tdwbport_number
Specify the port of the broker server to which the agent is connected. The default value is 31116. If you set the jwt parameter to true, ensure you provide a value for this parameter, to download the JWT and agent ID from the dynamic domain manager. The dynamic domain manager routes the JWT request to the master domain manager
--work_dir working_dir
The working directory used to store the waCertificates.zip file returned by the command. This compressed file contains the certificates in .PEM format retrieved from the master domain manager. This parameter is required and no default value is provided.
--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.
--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.

You can also use the wapassword and wauser parameters to specify a user different from the user which installed the master domain manager by using an ACL, as described in Downloading certificates or JWT using a different user.

For more information about the typical installation procedure, see Typical installation scenario.