TWS 8.3 and higher Command Line Client

by Pete Meechan

Starting with TWS 8.3 IBM introduced some major architectural changes to the Tivoli Workload Scheduler (TWS) for the distributed platforms. Amongst these changes was the introduction of WebSphere Application Server (WAS), installed as a component part of the Master Domain Manager (MDM).

TWS 8.3 and later versions also introduced the option to install a TWS command line client or CLI. This component can be installed on systems that do not have any other TWS component installed (i.e. without a FTA). The TWS CLI component provides local command capability for the following commands

  • composer
  • optman
  • planman showinfo
  • planman unlock

The TWS CLI does not provide access to the conman command as this requires a local copy of the Symphony file. However, if the TWS CLI component is installed on a system hosting an FTA, you would then have access to the most common TWS commands locally.

Although the TWS CLI was introduced with TWS 8.3, documentation covering the connection and security settings was omitted from the TWS documentation until TWS 8.5.

TWS Local options

As TWS supports multiple instances being installed on the same system, it is important to ensure that the TWS command being issued is directed to the correct TWS instance. This is achieved by referring to settings within the localopts file found in $TWS_HOME directory of each installed TWS instance.

The settings shown below are typical of the localopt settings found following the standard TWS installation for the MDM (these can be found towards the bottom of the localopts file)

#----------------------------------------------------------------------------
# Attributes for CLI connections
#
HOST = 127.0.0.1 # Master hostname used when attempting a connection.
PROTOCOL = https # Protocol used to establish a connection with the Master.
PORT = 31116 # Protocol port
#PROXY = proxy.userlocal
#PROXYPORT = 3333
TIMEOUT = 3600 # Timeout in seconds to wait a server response
#CLISSLSERVERAUTH = yes
#CLISSLCIPHER = MD5
#CLISSLSERVERCERTIFICATE =
#CLISSLTRUSTEDDIR =
DEFAULTWS = LINKWOOD
USEROPTS = useropts_twsuser

The HOST parameter identifies the hostname (or IP address) of the MDM. The PROTOCOL parameter determines whether http or http is used for the connection to the port specified by the PORT parameter.

If a connection is being made through a proxy server, specify the PROXY and PROXYPORT settings accordingly.

The TIMEOUT parameter specifies the time in seconds to wait for a response before indicating the command has failed. The CLISSLxxxx parameters are only required if SSL communiation is used from the remote client (CLISSLSERVERAUTH=yes)

The DEFAULTWS identifies the default workstation for command execution and is normally set to the MDM.

The USEROPTS setting identifies the name of the user options file containing user specific settings such as username and password. The default value for this setting is useropt_<twsuser> where <twsuser> is the user used to install TWS.

TWS User options

The TWS user options file is identified by the USEROPTS setting within the $TWS_HOME/localopts file. The file MUST be located within .TWS directory in the home directory of the user. For linux or UNIX this is generally the /home/user/.TWS directory (e.g. ~/.TWS). For Windows this is generally the C:Documents and Settingsuser.TWS (e.g. %USERPROFILE%.TWS).

Within the .TWS directory locate the filename identified by the USEROPTS parameter. Note that the name of this file is suffixed with the username of the user used to install TWS and is therefore the same name for each user using TWS – i.e. it is NOT suffixed by the name of the user attempting to use TWS.

The user attempting to use TWS will need to be defined within the TWS security file with the appropriate authority to execute the command being executed. In the examples shown below the user issuing the TWS command is twsuser1

The output below shows the twsuser1 logged in and the path to the home directory.

[ twsuser1@linkwood .TWS]$ id
uid=505(twsuser1) gid=505(twsuser1) groups=501(tws),505(twsuser1)
[ twsuser1@linkwood .TWS]$ pwd
/home/twsuser1/.TWS

The user used to install TWS is the user twsuser and therefore the user options file is named useropts_twsuser. The sample below shows the contents before any TWS commands have been issued (i.e. the password is in clear text)

[ twsuser1@linkwood .TWS]$ cat useropts_twsuser 
#
# TWS useropts file defines credential attributes of the remote Workstation.
#
USERNAME = twsuser1
PASSWORD = orbdata
[ twsuser1@linkwood .TWS]$

The sample below shows the user twsuser1 issuing the composer command to display the LINKWOOD workstation definition. TWS determines where to route the command using the HOST setting in the localopts file and presents the user and password obtained from the useropts_twsuser file described earlier.

[ twsuser1@linkwood .TWS]$ composer display cpu=LINKWOOD@
Tivoli Workload Scheduler (UNIX)/COMPOSER 8.5 (20081122)
Licensed Materials - 
				
Property of IBM(R)
5698-WSH
(C) Copyright IBM Corp 1998, 2008 All rights reserved.
US Government User Restricted Rights
Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
IBM is a registered trademark of International Business Machines
Corporation in the United States, other countries, or both.
Installed for user "twsuser".
Locale LANG set to the following: "en"
User: twsuser1, Host:127.0.0.1, Port:31116
-display cpu=LINKWOOD@
AWSBIA299I Looking for Workstation objects.

Workstation Name Type Domain Ignored Updated On Locked By
—————- ——- —————- ——- ———-

LINKWOOD manager MASTERDM 2009/03/04 -

CPUNAME LINKWOOD
DESCRIPTION “MASTER CPU”
OS UNIX
NODE linkwood.scotchwhisky.local TCPADDR 31111
DOMAIN MASTERDM
FOR MAESTRO
TYPE MANAGER
AUTOLINK ON
BEHINDFIREWALL OFF
FULLSTATUS ON
END

AWSBIA299I Looking for Workstation Class objects.
AWSJCL017W No objects have been found that match the criteria
in the command.

AWSBIA299I Looking for Domain objects.
AWSJCL017W No objects have been found that match the criteria

in the command.

AWSBIA291I Total objects: 1
[ twsuser1@linkwood .TWS]$

After issuing the command the password is now encrypted as can be seen below.

[ twsuser1@linkwood .TWS]$ cat useropts_twsuser 
#
# TWS useropts file defines credential attributes of the remote Workstation.
#
USERNAME = twsuser1
PASSWORD = "ENCRYPT:JYFkJblZ9P8="
[ twsuser1@linkwood .TWS]$

Overriding user options

As discussed above, the settings in localopts and useropt_twsuser will be used to determine the HOST MDM to which the command will be routed and the user/password for authentication and authorisation within TWS.

The conman, composer and planman command syntax has been updated to support specification of the TWS connection parameters. The following options can be specified BEFORE the sub-command for each of the listed commands.

-host <hostName>
-port <portNumber>
-protocol http | https
-proxy <proxyName>
-proxyport <proxyPortNumber>
-password <password>
-timeout <seconds>
-username <userName>

If any of the above options are omitted, the corresponding value found in the local options or user options file will be used instead.

The sample below shows the composer command being used to display a workstation named TALISKER on Windows and overriding the default user/password from the user options file.

C:Program FilesIBMTWATWS>whoami
talisker\administrator
C:Program FilesIBMTWATWS>type "%userprofile%.twsuseropts_twsuser"
#
# TWS useropts defines credential attributes of the remote Workstation.
#
USERNAME = twsuser
PASSWORD = "ENCRYPT:JYFkJblZ9P8="
C:Program FilesIBMTWATWS>composer -host talisker 
-user administrator -password orbdata
display cpu=talisker@
Tivoli Workload Scheduler (Windows)/COMPOSER 8.5 (20081124)
Licensed Materials - Property of IBM(R)
5698-WSH
(C) Copyright IBM Corp 1998, 2008 All rights reserved.
US Government User Restricted Rights
Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
IBM is a registered trademark of International Business Machines
Corporation in the United States, other countries, or both.
Installed for user "TALISKER wsuser".
Locale LANG set to the following: "en"
User: administrator, Host:talisker, Port:31116
-display cpu=talisker@
AWSBIA299I Looking for Workstation objects.
Workstation Name Type Domain OsType Ignored Updated By 
				
---------------- ------- ---------- ------- ------- ----------- 
				
TALISKER manager MASTERDM W twsuser 03/23/2009 
				
CPUNAME TALISKER
DESCRIPTION "MASTER CPU"
OS WNT
NODE TALISKER TCPADDR 31111
DOMAIN MASTERDM
FOR MAESTRO
TYPE MANAGER
AUTOLINK ON
BEHINDFIREWALL OFF
FULLSTATUS ON
END
AWSBIA299I Looking for Workstation Class objects.
AWSJCL017W No objects have been found that match the criteria
in the command.
				
AWSBIA299I Looking for Domain objects.
AWSJCL017W No objects have been found that match the criteria
in the command.
				
AWSBIA291I Total objects: 1
				
C:Program FilesIBMTWATWS>
				

Please refer to the TWS 8.5.1.x Administration guide for full details of the localopts and useropts files.

Visits: 1069