workload scheduler version 8 - ibm - united states for an oracle database .....98 preventing a...

Workload SchedulerVersion 8.6

Administration Guide

SC23-9113-03

��

NoteBefore using this information and the product it supports, read the information in Notices.

This edition applies to version 8, release 6 of IBM Tivoli Workload Scheduler (program number 5698-WSH) and toall subsequent releases and modifications until otherwise indicated in new editions.

This edition replaces SC23-9113-02

© Copyright IBM Corporation 2001, 2011.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

List of figures. . . . . . . . . . . . vii

List of tables . . . . . . . . . . . . ix

About this publication . . . . . . . . xiWhat is new in this release . . . . . . . . . xiWhat is new in this publication . . . . . . . . xiWho should read this publication . . . . . . . xiPublications . . . . . . . . . . . . . . xiiAccessibility . . . . . . . . . . . . . . xiiTivoli technical training . . . . . . . . . . xiiSupport information . . . . . . . . . . . xii

Chapter 1. Getting started withadministration . . . . . . . . . . . . 1Where products and components are installed . . . 1

Tivoli Workload Automation . . . . . . . . 1Tivoli Workload Automation instance . . . . . 1Installation paths . . . . . . . . . . . . 2Finding out what has been installed in whichTivoli Workload Automation instances . . . . . 4

Chapter 2. Customizing and configuringTivoli Workload Scheduler . . . . . . . 7Setting global options . . . . . . . . . . . 7

optman . . . . . . . . . . . . . . . 7Global options - summary . . . . . . . . . 9Global options - detailed description . . . . . 13

Setting local options . . . . . . . . . . . 23Localopts summary. . . . . . . . . . . 24Localopts details. . . . . . . . . . . . 26Local options file example . . . . . . . . 38

Setting user options . . . . . . . . . . . 41Sample useropts file . . . . . . . . . . 42Multiple product instances . . . . . . . . 42

Configuring the Tivoli Workload Scheduler agent. . 43Configuring log message properties[JobManager.Logging.cclog] . . . . . . . . 43Configuring trace properties[JobManager.Logging.cclog] . . . . . . . . 44Configuring common launchers properties[Launchers] . . . . . . . . . . . . . 45Configuring properties of the native job launcher[NativeJobLauncher] . . . . . . . . . . 46Configuring properties of the Java job launcher[JavaJobLauncher] . . . . . . . . . . . 47Configuring properties of the Resource advisoragent [ResourceAdvisorAgent] . . . . . . . 47Configuring properties of the System scanner[SystemScanner] . . . . . . . . . . . . 49

Configuring the dynamic workload broker server onthe master domain manager and dynamic domainmanager . . . . . . . . . . . . . . . 49

Maintaining the dynamic workload broker serveron the master domain manager and dynamicdomain manager . . . . . . . . . . . 50Enabling unsecure communication with thedynamic workload broker server . . . . . . 51ResourceAdvisorConfig.properties file . . . . 52JobDispatcherConfig.properties file . . . . . 54BrokerWorkstation.properties file . . . . . . 56Archiving job data . . . . . . . . . . . 57Configuring to schedule J2EE jobs . . . . . . 59Configuring to schedule job types with advancedoptions . . . . . . . . . . . . . . . 66Configuring security roles for users and groups 67

Configuring command-line client accessauthentication . . . . . . . . . . . . . 70

Connection parameters . . . . . . . . . 71Entering passwords. . . . . . . . . . . 73

Tivoli Workload Scheduler console messages andprompts . . . . . . . . . . . . . . . 73

Setting sysloglocal on UNIX . . . . . . . . 74console command . . . . . . . . . . . 74

Enabling the time zone feature . . . . . . . . 75Configuring to use the report commands . . . . 75Modifying jobmon service rights for Windows. . . 75

Chapter 3. Configuring the DynamicWorkload Console . . . . . . . . . . 77Launching in context with the Dynamic WorkloadConsole. . . . . . . . . . . . . . . . 77

Scenarios . . . . . . . . . . . . . . 77Advanced optional parameters . . . . . . . 79

Configuring access to the Dynamic WorkloadConsole. . . . . . . . . . . . . . . . 83

Configuring a user registry . . . . . . . . 83Configuring the Dynamic Workload Console touse the local OS authentication method . . . . 83Configuring roles to access the DynamicWorkload Console . . . . . . . . . . . 84

Configuring Dynamic Workload Console to useSingle Sign-On . . . . . . . . . . . . . 87

LTPA token-keys. . . . . . . . . . . . 88Configuring the use of Lightweight Third-PartyAuthentication . . . . . . . . . . . . . 88

Configuring to use the same LTPA token_keys. . 89Disabling the automatic generation of LTPAtoken_keys . . . . . . . . . . . . . 91

Configuring Dynamic Workload Console to use SSL 92Customizing Dynamic Workload Console(Advanced configuration). . . . . . . . . . 92

Customizing your global settings . . . . . . 92Managing Dynamic Workload Console settingsrepository . . . . . . . . . . . . . . . 97Configuring Dynamic Workload Console to viewreports . . . . . . . . . . . . . . . . 97

Configuring for a DB2 database . . . . . . 97

© Copyright IBM Corp. 2001, 2011 iii

|||||||

||

|||

|||||||||||

||||||||

Configuring for an Oracle database . . . . . 98Preventing a connection to specific Tivoli WorkloadScheduler Version 8.3 engines . . . . . . . . 99

Chapter 4. Configuring userauthorization (Security file) . . . . . 101Security management overview . . . . . . . 101Getting started . . . . . . . . . . . . . 102Updating the security file . . . . . . . . . 102

dumpsec . . . . . . . . . . . . . . 103makesec . . . . . . . . . . . . . . 104

Centralized security management . . . . . . 105Centralized security usage notes . . . . . . 106

Configuring the security file . . . . . . . . 106Security file syntax . . . . . . . . . . 107Specifying user attributes . . . . . . . . 108Specifying object types . . . . . . . . . 113Specifying object attributes . . . . . . . . 114Specifying access . . . . . . . . . . . 119The TWS_user - special security fileconsiderations . . . . . . . . . . . . 133

Sample security file . . . . . . . . . . . 133TWS_users and root users logged in on themaster domain manager. . . . . . . . . 133TWS_users and root users logged in on anydomain manager (other than the master) . . . 134TWS_users and root users logged in on anyworkstation other than any domain manager . . 134Users logged into the sys group on the masterdomain manager . . . . . . . . . . . 135Users logged into the sys group on anyworkstation other than the master domainmanager . . . . . . . . . . . . . . 136Users logged into the mis group on anyworkstation . . . . . . . . . . . . . 136Users logged in to multiple groups [continuekeyword] . . . . . . . . . . . . . . 137All other users logged in on any workstation 138

Chapter 5. Configuring authentication 139Where to configure authentication . . . . . . 139Available configurations . . . . . . . . . . 140How to configure authentication . . . . . . . 140

A typical configuration scenario . . . . . . 141Rules for using a Federated User Registry withTivoli Workload Scheduler . . . . . . . . . 141Configuring authentication using the IntegratedSolutions Console . . . . . . . . . . . . 142Configuring authentication using the WebSphereApplication Server tools . . . . . . . . . . 143

Security properties: reference . . . . . . . 144ChangeSecurityProperties - output . . . . . 153

Completing the configuration . . . . . . . . 1541. Create users and groups . . . . . . . . 1542. Update the Tivoli Workload Schedulersecurity file . . . . . . . . . . . . . 1543. Update associated WebSphere ApplicationServer properties . . . . . . . . . . . 1544. Propagate the changes . . . . . . . . 155

Example configurations of LDAP servers . . . . 155

Using the Pluggable Authentication Module . . . 157

Chapter 6. Network administration 159Network overview . . . . . . . . . . . 159Network definitions . . . . . . . . . . . 160Network communications . . . . . . . . . 160

Network links . . . . . . . . . . . . 161Network operation . . . . . . . . . . . 162

Network processes . . . . . . . . . . 163Optimizing the network . . . . . . . . . . 166

Data volumes . . . . . . . . . . . . 167Connectivity. . . . . . . . . . . . . 167Planning space for queues . . . . . . . . 168Tuning mailman servers . . . . . . . . . 174

Netman configuration file . . . . . . . . . 175Determining internal Symphony table size. . . . 176Extended agents . . . . . . . . . . . . 176

UNIX extended agents . . . . . . . . . 177IP address validation . . . . . . . . . . . 179

Support for Internet Protocol version 6 . . . . 179Operating system configuration (UNIX only) 180IP address validation messages . . . . . . 180

Impact of network changes . . . . . . . . . 181

Chapter 7. Setting connection security 183Connection security overview . . . . . . . . 183Using SSL for netman and conman . . . . . . 183

Setting up private keys and certificates . . . . 184Creating Your Own Certification Authority . . 185Creating private keys and certificates . . . . 186Configuring SSL attributes . . . . . . . . 187Configuring the SSL connection protocol for thenetwork . . . . . . . . . . . . . . 188Configuring full SSL security . . . . . . . 189

Interface communication . . . . . . . . . 192Overview. . . . . . . . . . . . . . 192Customizing the connector configuration files 194Changing a server key . . . . . . . . . 195Customizing the SSL connection for theDynamic Workload Console . . . . . . . 196Customizing the SSL connection to the masterdomain manager and dynamic domain manager 197Customizing the SSL connection for acommand-line client . . . . . . . . . . 199

Working across firewalls. . . . . . . . . . 200Configuring Tivoli Workload Scheduler to useLDAP . . . . . . . . . . . . . . . . 201FIPS compliance . . . . . . . . . . . . 201

FIPS overview . . . . . . . . . . . . 202Using FIPS certificates . . . . . . . . . 202Configuring SSL to be FIPS-compliant . . . . 206Configuring DB2 for FIPS . . . . . . . . 209Using Dynamic Workload Console and FIPS . . 214Configuring dynamic workload broker for FIPS 215Configuring batch reports for FIPS . . . . . 215Configuring LDAP for FIPS . . . . . . . 216Finding the GSKit version on agents running onUNIX and Linux operating systems . . . . . 216

Chapter 8. Data maintenance. . . . . 217

iv IBM Tivoli Workload Scheduler: Administration Guide

|||

|||

|||

Maintaining the database . . . . . . . . . 217Backing up and restoring . . . . . . . . 217Reorganizing the database . . . . . . . . 219

Maintaining the file system. . . . . . . . . 220Avoiding full file systems . . . . . . . . 220Log files and archived files . . . . . . . . 223Temporary files. . . . . . . . . . . . 225Managing event message queue file sizes . . . 225

Administrative tasks - DB2 . . . . . . . . . 225Changing DB2 passwords . . . . . . . . 225Locating the DB2 tools . . . . . . . . . 225User permissions for running the DB2 tools . . 226Administering the DB2 maintenance feature . . 226Reorganizing the DB2 database . . . . . . 228Monitoring the lock list memory . . . . . . 229

Administrative tasks - Oracle . . . . . . . . 231Changing the Oracle access password . . . . 232Locating the Oracle tools . . . . . . . . 232Maintaining the Oracle database . . . . . . 232Obtaining information about the TivoliWorkload Scheduler databases installed on anOracle instance . . . . . . . . . . . . 232User permissions for running the Oracle tools 233

Migrating data from DB2 to Oracle and vice versa 233Parallel data migration from DB2 to Oracle . . 234Parallel data migration from Oracle to DB2 . . 235Reconfiguration from DB2 to Oracle . . . . . 237Reconfiguration from Oracle to DB2 . . . . . 242

Upgrading your database . . . . . . . . . 247Auditing facilities . . . . . . . . . . . . 248

Database and plan audit. . . . . . . . . 248Dynamic workload scheduling audit . . . . 254Keeping track of database changes using auditreports . . . . . . . . . . . . . . 263

Chapter 9. Administrative tasks . . . 267Changing a domain manager or dynamic domainmanager . . . . . . . . . . . . . . . 269

Choosing a backup domain manager or backupdynamic domain manager . . . . . . . . 269Setting up a backup domain manager . . . . 269Network security . . . . . . . . . . . 269Switching a domain manager . . . . . . . 270Switching a dynamic domain manager . . . . 270

Changing a master domain manager . . . . . 270Choosing a workstation for backup masterdomain manager . . . . . . . . . . . 270Setting up a backup master domain manager 271Copying files to use on the backup masterdomain manager . . . . . . . . . . . 271Switching a master domain manager . . . . 272Extended loss or permanent change of masterdomain manager . . . . . . . . . . . 272Switching a master domain manager ordynamic domain manager . . . . . . . . 273

Changing key Tivoli Workload Schedulerpasswords . . . . . . . . . . . . . . 274

Determining the role of the user whosepassword has changed . . . . . . . . . 276Determining the actions to take . . . . . . 277

Action 1 - change the WebSphere ApplicationServer user ID password . . . . . . . . 278Action 2 - change password used bycommand-line clients to access the masterdomain manager . . . . . . . . . . . 279Action 3 - change password used byfault-tolerant agent systems to access the masterdomain manager (for conman) . . . . . . 279Action 4 - update the engine connectionparameters in the GUIs . . . . . . . . . 280Action 5 - change the j2c user ID password . . 280Action 6 - update SOAP properties . . . . . 281Action 7 - Windows - update Windows services 281Action 8 - change the Tivoli Workload SchedulerWindows user definition . . . . . . . . 281Using the changePassword script . . . . . . 282

Unlinking and stopping Tivoli Workload Scheduler 283Changing the database host name, port, ordatabase name . . . . . . . . . . . . . 285

Change the DB2 host name, port, or databasename . . . . . . . . . . . . . . . 285Changing the Oracle host name, port, ordatabase name . . . . . . . . . . . . 291

Changing the workstation host name or IP address 291Reporting the changes in the WebSphereApplication Server configuration file . . . . 292Reporting the changed host name or IP addressof the workstation where you installed theRDBMS . . . . . . . . . . . . . . 293Reporting the changed host name or IP addressin the workstation definition . . . . . . . 294Reporting the changed host name or IP addressof the dynamic workload broker server. . . . 295Reporting the changed host name or IP addressof the dynamic agent . . . . . . . . . . 296

Changing the security settings. . . . . . . . 296Managing the event processor . . . . . . . . 297Starting, stopping, and displaying dynamicworkload broker status . . . . . . . . . . 298Automatically initializing Tivoli WorkloadScheduler instances . . . . . . . . . . . 299Application server tasks . . . . . . . . . . 300

Application server - starting and stopping. . . 300Application server - automatic restart afterfailure . . . . . . . . . . . . . . . 301Application server - encrypting the profileproperties files . . . . . . . . . . . . 305Application server - updating the Windowsservices after modifications . . . . . . . . 305Application server - updating the SOAPproperties after changing the WebSphereApplication Server user or its password . . . 306Application server - configuration files backupand restore . . . . . . . . . . . . . 307Application server - changing the host name orTCP/IP ports . . . . . . . . . . . . 308Application server - changing the traceproperties . . . . . . . . . . . . . 311WebSphere Application Server tools - reference 312

Chapter 10. Performance . . . . . . 317

Contents v

|||||||||

||||||||||||||

|||

||||||||||||||||||

|||

Network traffic . . . . . . . . . . . . . 317Tracing . . . . . . . . . . . . . . . 317Logging . . . . . . . . . . . . . . . 318Maintaining the database . . . . . . . . . 318Symphony file sizing . . . . . . . . . . . 318Tuning a UNIX domain manager to handle largenumbers of fault-tolerant agents . . . . . . . 318Tuning job processing on a workstation . . . . 318Tuning the database . . . . . . . . . . . 319Tuning the embedded WebSphere ApplicationServer . . . . . . . . . . . . . . . . 319

Inadequate Java heap size . . . . . . . . 320Too many manual job submissions . . . . . . 320Too many file dependency checks . . . . . . 320Workload spreading . . . . . . . . . . . 320Improving job-processing performance . . . . . 320Mailbox caching - advantages and disadvantages 321Setting the synch level parameter. . . . . . . 322The fault-tolerant switch manager - impact onperformance . . . . . . . . . . . . . . 322

Network Traffic . . . . . . . . . . . 323

Disk Space . . . . . . . . . . . . . 323Scalability . . . . . . . . . . . . . . 323

Impact on JnextPlan . . . . . . . . . . 323Impact on reporting . . . . . . . . . . 324Impact on event rule deployment . . . . . 324Increasing application server heap size . . . . 324Increasing maximum DB2 log capacity . . . . 325

Multiple Dynamic Workload Console productionplan reports . . . . . . . . . . . . . . 328Dynamic Workload Console - adjusting sessiontimeout settings . . . . . . . . . . . . 329

Chapter 11. Availability . . . . . . . 331Resolving Windows user ID account . . . . . 331Using a temporary directory on UNIX . . . . . 331

Notices . . . . . . . . . . . . . . 333Trademarks . . . . . . . . . . . . . . 334

Index . . . . . . . . . . . . . . . 337

vi IBM Tivoli Workload Scheduler: Administration Guide

List of figures

1. List of tasks . . . . . . . . . . . . 822. Tivoli Workload Scheduler network domain

structure . . . . . . . . . . . . . 1593. Symphony file synchronization . . . . . 1634. Process creation on domain manager and

fault-tolerant agent. . . . . . . . . . 164

5. Typical Tivoli Workload Scheduler networkflows. . . . . . . . . . . . . . . 168

6. SSL server and client keys . . . . . . . 193

© Copyright IBM Corp. 2001, 2011 vii

viii IBM Tivoli Workload Scheduler: Administration Guide

List of tables

1. Workload service assurance feature . . . . . 92. Event-driven workload automation feature -

general . . . . . . . . . . . . . . 103. Event-driven workload automation feature -

event mailing . . . . . . . . . . . . 104. SSL . . . . . . . . . . . . . . . 105. Job management . . . . . . . . . . . 116. Job stream management . . . . . . . . 117. Stageman . . . . . . . . . . . . . 118. Planman . . . . . . . . . . . . . 119. Logging and auditing . . . . . . . . . 12

10. Cross dependencies . . . . . . . . . . 1211. General . . . . . . . . . . . . . . 1212. Valid encryption cipher classes . . . . . . 2913. JOA_JOB_ARCHIVES database table . . . . 5814. JRA_JOB_RESOURCE_ARCHIVES database

table . . . . . . . . . . . . . . . 5815. MEA_METRIC_ARCHIVES database table 5916. Job statuses in the historical tables . . . . . 5917. J2EEJobExecutorConfig.properties file

keywords . . . . . . . . . . . . . 6018. Configuration files for job types with advanced

options . . . . . . . . . . . . . . 6619. Default port numbers . . . . . . . . . 7820. Product versions and default server names 9021. Syntax for special characters . . . . . . . 9522. Variables used in the URL definition . . . . 9523. Object attribute types for each object type 11524. Access keywords for composer actions 12125. Actions - access keywords . . . . . . . 12226. Calendar - additional access keywords 12327. Cpus - additional access keywords . . . . 12428. Events - access keywords . . . . . . . 12529. Files - access keywords . . . . . . . . 12530. Jobs - additional access keywords . . . . . 12631. Parameters - additional access keywords 129

32. Prompts - additional access keywords 12933. Files- access keywords . . . . . . . . 13034. Resources - additional access keywords 13035. Job streams - additional access keywords 13136. Users - additional access keywords . . . . 13137. Variable tables - access keywords . . . . . 13238. Critical flow errors. . . . . . . . . . 16939. Queue sizing conditions. . . . . . . . . 17040. Example for the ge operator . . . . . . 17141. Example for the le operator . . . . . . . 17242. Calculation of internal Symphony table 17643. Files for Local Options . . . . . . . . 18744. Type of communication depending on the

securitylevel value . . . . . . . . . . 18845. Changes allowed in Tivoli Workload

Scheduler key and trust stores . . . . . . 19446. Algorithm for calculating the approximate

size of the plan data in the Symphony file . . 22047. Algorithm for calculating the approximate

size of the database data in the Symphonyfile . . . . . . . . . . . . . . . 221

48. Example for the ge operator . . . . . . 22249. Example for the le operator . . . . . . . 22250. Log and trace file maintenance. . . . . . 22351. Auditable event properties . . . . . . . 25652. Elements in Action type . . . . . . . . 25753. Elements in ObjectInfoList type . . . . . 25754. Elements in ObjectInfo type . . . . . . . 25755. Elements in Outcome type . . . . . . . 25856. Elements in UserInfoList type . . . . . . 25957. Elements in UserInfo type . . . . . . . 25958. If and where password changes are required 27559. Values of activeUserRegistry to check 27660. Password change actions. . . . . . . . 27761. Options for tuning job processing on a

workstation . . . . . . . . . . . . 319

© Copyright IBM Corp. 2001, 2011 ix

||

|||

||||

||||||||||||||

x IBM Tivoli Workload Scheduler: Administration Guide

About this publication

IBM® Tivoli® Workload Scheduler: Administration provides information about theadministration of the main components of IBM Tivoli Workload Scheduler (oftencalled the engine).

What is new in this release

For information about the new or changed functions in this release, see TivoliWorkload Automation: Overview.

For information about the APARs that this release addresses, see the TivoliWorkload Scheduler Download Document at http://www.ibm.com/support/docview.wss?rs=672&uid=swg24027501, and Dynamic Workload ConsoleDownload Document at http://www.ibm.com/support/docview.wss?rs=672&uid=swg24029125.

What is new in this publication

The following sections have been added or modified since version 8.5.1:v “Rules for using a Federated User Registry with Tivoli Workload Scheduler” on

page 141v “Configuring the dynamic workload broker server on the master domain

manager and dynamic domain manager” on page 49v “Configuring to schedule job types with advanced options” on page 66v “Configuring access to the Dynamic Workload Console” on page 83v “Auditing facilities” on page 248v “Changing a domain manager or dynamic domain manager” on page 269.v “Changing the workstation host name or IP address” on page 291

For more information about the new or changed functions in this release, see TivoliWorkload Automation: Overview.

Changed or added text with respect to the previous version is marked by a verticalbar in the left margin.

Who should read this publication

This publication provides information about the day-to-day administration of theproduct, and is aimed at the IT administrator or Tivoli Workload Scheduler ITadministrator whose job it is to ensure that the product runs smoothly andcorrectly. This person will find information about making routine changes to theconfiguration, for example to add a user, and information about periodicprocedures that ensure the integrity of the product, such as backups.

The reader of this book should be an expert systems programmer, who has areasonable understanding of the Tivoli Workload Scheduler infrastructure and itsinter-component interactions.

© Copyright IBM Corp. 2001, 2011 xi

http://www.ibm.com/support/docview.wss?rs=672&uid=swg24027501




Publications

Full details of Tivoli Workload Automation publications can be found in TivoliWorkload Automation: Publications. This document also contains information aboutthe conventions used in the publications.

A glossary of terms used in the product can be found in Tivoli Workload Automation:Glossary.

Both of these are in the Information Center as separate publications.

Accessibility

Accessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

For full information with respect to the Dynamic Workload Console, see theAccessibility Appendix in the Tivoli Workload Scheduler: User's Guide and Reference,SC32-1274.

Tivoli technical training

For Tivoli technical training information, refer to the following IBM TivoliEducation website:

http://www.ibm.com/software/tivoli/education

Support information

If you have a problem with your IBM software, you want to resolve it quickly. IBMprovides the following ways for you to obtain the support you need:

OnlineGo to the IBM Software Support site at http://www.ibm.com/software/support/probsub.html and follow the instructions.

IBM Support AssistantThe IBM Support Assistant (ISA) is a free local software serviceabilityworkbench that helps you resolve questions and problems with IBMsoftware products. The ISA provides quick access to support-relatedinformation and serviceability tools for problem determination. To installthe ISA software, go to http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the problemdetermination information for this product.

For more information about these three ways of resolving problems, see theappendix on support information in Tivoli Workload Scheduler: Troubleshooting Guide,SC32-1275.

xii IBM Tivoli Workload Scheduler: Administration Guide

http://www.ibm.com/software/tivoli/education

http://www.ibm.com/software/support/probsub.html

http://www.ibm.com/software/support/probsub.html

http://www.ibm.com/software/support/isa

Chapter 1. Getting started with administration

This publication describes how to perform administrative tasks on Tivoli WorkloadScheduler and Dynamic Workload Console. Many of the procedures described in itrequire you to identify a file in the installation path of the product and itscomponents. However, these files might be in different installation paths fordifferent components or on different systems, as described in “Where products andcomponents are installed.”

Where products and components are installedThis section commences by briefly introducing Tivoli Workload Automation andexplaining how this concept impacts the installed structure of Tivoli WorkloadScheduler.

Tivoli Workload AutomationTivoli Workload Automation is the name of a family of products and components,which includes the following:v Tivoli Workload Schedulerv Tivoli Workload Scheduler for z/OS®

v Tivoli Workload Scheduler for Applicationsv Dynamic Workload Consolev Tivoli Workload Scheduler for Virtualized Data Centresv Tivoli Workload Scheduler LoadLeveler®

Many Tivoli Workload Scheduler components are installed in what is called a TivoliWorkload Automation instance.

Tivoli Workload Automation instanceWhat is a Tivoli Workload Automation instance? You need to know the answer tothis question to understand how multiple products and components are installedon the same system. The Tivoli Workload Automation products and componentsuse the embedded WebSphere® Application Server as the communicationinfrastructure. To make the most efficient use of the WebSphere Application Server,several products and components can be installed together, using one instance ofWebSphere Application Server, in a "Tivoli Workload Automation instance".

Contents: WebSphere Application Serverand other infrastructure tools

TWA Instance: Default UNIX path:

opt/IBM/TWA

Contents: WebSphere Application Serverand other infrastructure tools

TWA Instance: Default UNIX path:

opt/IBM/TWA

Master domain manager,backup master, or agent TWS

Server

Reserved forfuture TWA product

Reserved forfuture TWA product

TWS for z/OSConnector

© Copyright IBM Corp. 2001, 2011 1

This image shows two instances of Tivoli Workload Automation. A component ofTivoli Workload Scheduler, the Tivoli Workload Scheduler for z/OS Connector, andthe Dynamic Workload Console are shown ready to be plugged in to the TivoliWorkload Automation instance. Each "Tivoli Workload Automation instance"contains an instance of the embedded WebSphere Application Server.

One instance of the following can be plugged in (installed into) a Tivoli WorkloadAutomation instance:v Any one of the following components of Tivoli Workload Scheduler: master

domain manager, backup master domain manager, or agentv Dynamic Workload Consolev Tivoli Workload Scheduler for z/OS connector

You can have any number of Tivoli Workload Automation instances on the samesystem, to contain the products and components you want to install on it. Anyother components of Tivoli Workload Scheduler, such as the command line client,are installed outside the Tivoli Workload Automation instance because they do notcurrently use the embedded WebSphere Application Server.

Installation pathsThis section describes the installation paths of the Tivoli Workload Schedulercomponents:

TWA_home installation pathAs described above, many of the components are installed in a TivoliWorkload Automation instance. Although this is a notional structure it isrepresented on the computer where you install Tivoli WorkloadAutomation components by a common directory referred to in thedocumentation as TWA_home. The path of this directory is determinedwhen you install a Tivoli Workload Scheduler component for the first timeon a computer. You have the opportunity to choose the path when youmake that first-time installation, but if you accept the default path, it is asfollows:

Linux /opt/IBM/TWA<n>

UNIX /opt/ibm/TWA<n>

WindowsC:\Program Files\IBM\TWA<n>

where <n> is an integer value ranging from <null> for the first instanceinstalled, 1 for the second, and so on.

This path is called, in the publications, TWA_home

Tivoli Workload Scheduler installation pathYou can install more than one Tivoli Workload Scheduler component(master domain manager, backup master domain manager, domainmanager, or backup domain manager) on a system, but each is installed ina separate instance of .Tivoli Workload Automation, as described above.

The installation path of Tivoli Workload Scheduler is:TWA_home/TWS

Tivoli Workload Scheduler agent installation pathThe agent also uses the same default path structure, but has its ownseparate installation directory:

2 IBM Tivoli Workload Scheduler: Administration Guide

TWA_home/TWS/ITA/cpa

Note: The agent also installs some files outside this path. If you have toshare, map, or copy the agent files (for example when configuringsupport for clustering) share, map, or copy these files, as well:

UNIX and Linux operating systems/etc/teb/teb_tws_cpa_agent_<TWS_user>.ini/opt/IBM/CAP/EMICPA_default.xml/etc/init.d/tebctl-tws_cpa_agent_<TWS_user>

(on Linux and Solaris)/etc/rc.d/init.d/tebctl-tws_cpa_agent_<TWS_user>

(on AIX)/sbin/init.d/tebctl-tws_cpa_agent_<TWS_user>

(on HP-UX)

Windows operating systems%windir%\teb\teb_tws_cpa_agent_<tws_user>.ini%ALLUSERSPROFILE%\Application Data\ibm\CAP\EMICPA_default.xml

The agent uses two configuration files which you might need to modify:

JobManager.iniThis file contains the parameters that tell the agent how to runjobs. You should only change the parameters if advised to do so inthe Tivoli Workload Scheduler documentation or requested to doso by IBM Software Support. Its path is:

TWA_home/TWS/ITA/cpa/config/JobManager.ini

ita.ini This file contains parameters which determine how the agentbehaves. Changing these parameters may compromise the agentfunctionality and require it to be reinstalled. You should onlychange the parameters if advised to do so in the Tivoli WorkloadScheduler documentation or requested to do so by IBM SoftwareSupport. Its path is:

TWA_home/TWS/ITA/cpa/ita/ita.ini

Installation path for files giving the dynamic scheduling capabilityThe files that give the dynamic scheduling capability are installed in thefollowing path:

TWA_home/TDWB

Dynamic Workload Console installation pathThe Dynamic Workload Console can be installed in more than one path:v It can be installed alongside Tivoli Workload Scheduler or alone in a

Tivoli Workload Automation instance using the embedded version ofWebSphere Application Server. In this case its path is:

TWA_home/TDWC

v It can be installed on your own external instance of WebSphereApplication Server. In this case its path depends on where your instanceof WebSphere Application Server is installed (except for the uninstaller,which is installed in a path of your choice). The administrativeprocedures in this publication do not address problems that occur withthe external version of WebSphere Application Server.If you are using the Dynamic Workload Console on an external versionof WebSphere Application Server, and an administrative procedure refersto the path TWA_home/TDWC, substitute it with the installation path of theDynamic Workload Console on your external version of WebSphereApplication Server

Chapter 1. Getting started with administration 3

The embedded WebSphere Application Server installation pathThe embedded WebSphere Application Server is automatically installedwhen you create a new Tivoli Workload Automation instance. Its installationpath is:

TWA_home/eWAS

The command line client installation pathThe command line client is installed outside all Tivoli Workload Automationinstances. Its default path is:

UNIX /opt/ibm/TWS/CLI

WindowsC:\Program Files\IBM\TWS\CLI

The application server tools installation pathBecause the embedded WebSphere Application Server is not supplied withan administration GUI, many of its administration tasks are performed byrunning tools supplied with Tivoli Workload Scheduler, that perform therequired configuration changes. These tools are known as the wastools, andare installed in:

TWA_home/wastools

However, the information above supplies only the default paths. To determine theactual paths of products and components installed in Tivoli Workload Automationinstances, see “Finding out what has been installed in which Tivoli WorkloadAutomation instances”

Finding out what has been installed in which Tivoli WorkloadAutomation instances

If you are not the installer of Tivoli Workload Scheduler and its components, youmight not know what components have been installed, and in which instances ofTivoli Workload Automation. Follow this procedure to find out:1. Access the following directory:

UNIX and Linux operating systems/etc/TWA

Windows operating systems%windir%\TWA

2. List the contents of the directory. Each Tivoli Workload Automation instance isrepresented by a file called: twainstance<instance_number>.TWA.properties.These files are deleted when all the products or components in an instance areuninstalled, so the number of files present indicates the number of validinstances currently in use.

3. Open a file in a text viewer.Attention: Do not edit the contents of this file, unless directed to do so byIBM Software Support. Doing so might invalidate your Tivoli WorkloadScheduler environment.The contents are similar to this:#TWAInstance registry#Mon Nov 24 15:35:02 CET 2008TWS_version=8.5.0.00EWas_basePath=C\:/Program Files/IBM/TWA/eWASTWS_counter=1EWas_counter=2


||||||

TWA_path=C\:/Program Files/IBM/TWATWS_server_name=twaserverTDWC_version=8.6.0.0TWS_instance_type=MDMEWas_profile_path=C\:/Program Files/IBM/TWA/eWAS/profiles/TIPProfileEWas_node_name=DefaultNodeTWS_basePath=C\:\\Program Files\\IBM\\TWA\\TWSEWas_user=twsuser86EWas_cell_name=DefaultNodeTDWC_EXTERNAL_WAS_KEY=falseEWas_version=7.0.0.15TDWC_counter=1EWas_server_name=twaserverEWas_update_installer_dir=C\:/Program Files/IBM/WebSphere/UpdateInstallerTDWC_basePath=C\:/Program Files/IBM/TWA/TDWCTWS_user_name=twsuser86TWS_FIX_LIST_KEY=TDWC_FIX_LIST_KEY=TWA_componentList=TWS,EWas,TDWCEWas_isc_version_key=7.1.0.06EWas_profile_name=TIPProfileEWas_service_name=twsuser85

The important keys to interpret in this file are:

TWA_pathThis is the base path, to which the installation added one or more ofthe following directories, depending on what was installed:

TWS Where the Tivoli Workload Scheduler component is installed

TDWC Where the Dynamic Workload Console is installed

eWAS Where the embedded WebSphere Application Server is installed

wastoolsWhere the tools that you use to configure the embeddedWebSphere Application Server are installed

ssm Where the Netcool® SSM monitoring agent is installed (used inevent management)

TWA_componentListLists the components installed in the instance of Tivoli WorkloadAutomation

TWS_counterIndicates if a Tivoli Workload Scheduler component is installed in thisinstance of Tivoli Workload Automation (when the value=1)

TWS_instance_typeIndicates which component of Tivoli Workload Scheduler is installed inthis instance:

MDM Master domain manager

BKM Backup master domain manager

DDM dynamic domain manager

BDDMBackup dynamic domain manager

FTA Fault-tolerant agent or domain manager

TDWC_counterIndicates if an instance of Dynamic Workload Console is installed inthis instance of Tivoli Workload Automation (when the value=1)

Chapter 1. Getting started with administration 5

||||||||||||||||||||||

EWas_counterIndicates how many applications are installed in this instance of TivoliWorkload Automation that access the embedded WebSphereApplication Server

TWS_user_nameThe ID of the <TWS_user> of the Tivoli Workload Schedulercomponent.

EWas_userThe ID of the administration user of the embedded WebSphereApplication Server. For a default installation, this is the same as the<TWS_user>.

The only component of Tivoli Workload Scheduler which is installed in a TivoliWorkload Automation instance, but which is not explicitly indicated here, is theConnector. To determine if it has been installed, look at the followingcombinations of keys:

Agent installed with no ConnectorTWS_counter=1EWas_counter=TWS_instance_type=FTATDWC_counter=TWA_componentList=TWS

Agent installed with ConnectorTWS_counter=1EWas_counter=1TWS_instance_type=FTATDWC_counter=TWA_componentList=TWS,EWas

Agent installed with no Connector and Dynamic Workload ConsoleTWS_counter=1EWas_counter=1TWS_instance_type=FTATDWC_counter=1TWA_componentList=TWS,EWas,TDWC

Agent installed with Connector and Dynamic Workload ConsoleTWS_counter=1EWas_counter=2TWS_instance_type=FTATDWC_counter=1TWA_componentList=TWS,EWas,TDWC

Note: The only difference between these last two is that theEWas_counter is 2 instead of 1.


Chapter 2. Customizing and configuring Tivoli WorkloadScheduler

After installing the product you can customize it to fit your operationalrequirements. You can also change the customized values at any time. This chapterdescribes the optional customization steps for Tivoli Workload Scheduler. It isdivided into the following sections:v “Setting global options”v “Setting local options” on page 23v “Setting user options” on page 41v “Configuring the dynamic workload broker server on the master domain

manager and dynamic domain manager” on page 49v “Configuring the Tivoli Workload Scheduler agent” on page 43v “Configuring command-line client access authentication” on page 70v “Tivoli Workload Scheduler console messages and prompts” on page 73v “Enabling the time zone feature” on page 75v “Configuring to use the report commands” on page 75

Note: For information about automating the production cycle and managing theproduction environment, see the User's Guide and Reference.

Setting global options

Set global options using the optman command.

optmanManages the Tivoli Workload Scheduler global options. You can list, show andchange them.

Authorization

You must have the following security permissions for the global options file in theTivoli Workload Scheduler security file to work with this command:v For optman ls or optman show:

FILE NAME=GLOBALOPTS ACCESS=DISPLAYv For optman chg:

FILE NAME=GLOBALOPTS ACCESS=MODIFY

See Chapter 4, “Configuring user authorization (Security file),” on page 101 formore information on the security file.

Syntax

optman [-u | -v]optman [<connectionParams>] chg {<option> | <shortName>} = <value>optman [<connectionParams>] lsoptman [<connectionParams>] show {<option> | <shortName>}


Arguments

<connectionParams>If you are using optman from the master domain manager, the connectionparameters were configured at installation and do not need to be supplied,unless you do not want to use the default values.

If you are using optman from the command line client on anotherworkstation, the connection parameters might be supplied by one or moreof these methods:v Stored in the localopts filev Stored in the useropts filev Supplied to the command in a parameter filev Supplied to the command as part of the command string

For full details of the connection parameters see “Configuringcommand-line client access authentication” on page 70.

chg {<option> | <shortName>} = <value>Change the value of an option to the new value supplied. The option caneither be identified by its full or its short name. See “Global options -summary” on page 9 for a table showing all of the options with their fulland short names, value ranges and default values. See “Global options -detailed description” on page 13 for a full description of each option.

ls Lists the current values of all global options.

show {<option> | <shortName>}Displays the current value of the indicated option. The option can either beidentified by its full or its short name. See “Global options - summary” onpage 9 for a table showing all of the options with their full and shortnames, value ranges and default values. See “Global options - detaileddescription” on page 13 for a full description of each option.

Comments

Some of the changes are effective immediately, but others require a specific action,such as running JnextPlan, restarting the WebSphere Application Server. Theseactions are indicated in the option descriptions. See Tivoli Workload Scheduler: User'sGuide and Reference for more information on the JnextPlan command.

Examples

Example 1: list the global optionsTo list all of the global options, when your connection parameters aresupplied via the localopts and useropts files, give the followingcommand:optman ls

Example 2: show the value of a global optionTo show the current value of the enCarryForward global option, identifyingit by its short name, give the following command:optman show cf

Example 3: change the value of a global optionTo change the current value of the enCarryForward global option,identifying it by its full name, give the following command:optman chg enCarryForward no


Global options - summaryThis section summarizes the global options that are managed by optman. Thecolumns in the tables have the following meanings:

DescriptionThe brief description of the option

Name The option as used in the optman commands.

Short nameThe shortName as used in the optman commands.

DefaultThe default value that is applied to the option at installation (if present).

Range The range or choice of values you can supply (where appropriate).

Units The units that apply to the default and range.

Effect How to make any changes effective. The following codes have been used:

E If you are enabling the option, start the Event Processor. If you aredisabling the option, stop the Event Processor.

Imm The change is effective immediately

Imm (DB)The change is effective immediately in the database only.

J Run JnextPlan.

J (Plan)Run JnextPlan - it makes the change effective in the plan only.

NSM The change is effective on the next send mail action.

W Restart the WebSphere Application Server

Global options grouped by feature or function

The following tables summarize the options for managing the features andfunctions of Tivoli Workload Scheduler:

Table 1. Workload service assurance feature

Description NameShortname Default Range Units Effect

Enable workload serviceassurance

enWorkloadServiceAssurance wa yes yes, no boolean J

Approaching late offset approachingLateOffset al 120 >=0 seconds J or W

Deadline offset deadlineOffset do 2 >=0 minutes J or W

Promotion offset promotionOffset po 120 >=0 seconds J

Enable forecast start timecalculation

enForecastStartTime st no yes, no boolean imm

Chapter 2. Customizing and configuring Tivoli Workload Scheduler 9

Table 2. Event-driven workload automation feature - general


Enable event drivenworkload automation

enEventDrivenWorkloadAutomation ed yes yes, no boolean J or E

Rules deployment frequency deploymentFrequency df 5 0-60 minutes Imm

Enable event processorHTTPS protocol

enEventProcessorHttpsProtocol eh yes yes, no boolean J

Tivoli event integrationfacility port

eventProcessorEIFPort ee 31131 0 -65535

portnumber

W andJ

Tivoli Enterprise Console®

server nameTECServerName th localhost name J

Tivoli Enterprise Consoleserver port

TECServerPort tp 5529 0 –65535

portnumber

J

Table 3. Event-driven workload automation feature - event mailing


Mail sender name mailSenderName ms TWS name NSM

SMTP server name smtpServerName sn localhost name Imm

SMTP Server port smtpServerPort sp 25 0 –65535

portnumber

NSM

Mail plug-in uses SMTPauthentication

smtpUseAuthentication ua no yes, no boolean Imm

SMTP user name smtpUserName un TWS_user name Imm

SMTP user password smtpUserPassword up Imm

Mail plug-in uses SSL smtpUseSSL us no yes, no boolean Imm

Mail plug-in uses TLSprotocol

smtpUseTLS tl no yes, no boolean Imm

Table 4. SSL


Enable the SSL fullconnection

enSSLFullConnection sf no yes, no boolean J

Enable strong passwordencryption

enStrEncrypt se no yes, no boolean J


Table 5. Job management


Maximum prompts afterabend

baseRecPrompt bp 1000 0 –65535

prompts J

Additional prompts afterabend

extRecPrompt xp 1000 0 –65535

prompts J

Concurrent access toresources

enExpandedResources er no yes, no boolean J

Automatically grant logon asbatch

enLogonBatch lb no yes, no boolean J

Long duration job threshold longDurationThreshold ld 150 100 -1000

seconds J or W

User for binding to remotejobs from shadow job

bindUser bu TWS_user Imm

Table 6. Job stream management


Job streams without jobspolicy

enEmptySchedsAreSucc es no yes, no boolean J

Prevent job stream without"at" dependency from starting

enPreventStart ps yes yes, no boolean J

Table 7. Stageman


Carry job states carryStates cs null list ofstates

J

Enable carry forward enCarryForward cf all all, no boolean J

Enable carry forward forinternetwork dependencies

enCFinterNetworkDeps ci yes yes, no boolean J

Enable carry forwardresource quantity

enCFResourceQuantity rq yes yes, no boolean J

Retain rerun job name enRetainNameOnRerunFrom rr no yes, no boolean J

Table 8. Planman


Maximum preproductionplan length

maxLen xl 8 8 - 365 days J

Minimum preproduction planlength

minLen ml 8 7 - 365 days J


Table 9. Logging and auditing


Log cleanup frequency logCleanupFrequency lc 5 0 - 60 minutes J

Log history period logHistory lh 10 >=0 days J

Logman minimum andmaximum run times policy

logmanMinMaxPolicy lm both literal J

Logman normal run timecalculation policy

logmanSmoothPolicy lt -1 0 - 100 factor J

Enable database auditing enDbAudit da 0 0, 1 boolean Imm

Type of store to be used tolog database audit records

auditStore as file db,file,both

Imm

Audit history period auditHistory ah 180 >=1 days Imm

Table 10. Cross dependencies


Number of days for retryingto send notifications aboutjob status changes to theremote engine if thenotification fails

notificationTimeout nt 5 1-90 Number Imm

Table 11. General


Company name companyName cn name J

Enable centralized security enCentSec ts no yes, no boolean J

Enable previous job streamID

enLegacyId li no yes, no boolean J

Evaluate start-of-day enLegacyStartOfDayEvaluation le no yes, no boolean J

Enable list security check enListSecChk sc no yes, no boolean J (Plan)Imm(DB)

Enable plan auditing enPlanAudit pa 0 0, 1 boolean J

Enable the fault-tolerantswitch manager

enSwfaultTol sw no yes, no boolean J

Enable time zones enTimeZone tz yes yes, no boolean J (Plan)Imm(DB)

Ignore calendars ignoreCals ic no yes, no boolean J

Start time of processing day startOfDay sd 0600 0000–2359

hhmm J


||

||||||||

|||||

||||||

|

Table 11. General (continued)


Job statistics history period statsHistory sh 10 >=0 days J (Plan)Imm(DB)

Global options - detailed descriptionThis section gives full descriptions of the global options managed by optman:

approachingLateOffset | alApproaching late offset. Used in workload service assurance. The criticalstart time of a job in the critical network is the latest time that the job canstart without causing the critical job to finish after the deadline. In mostcases, a job will start well before the critical start time so that if the jobruns longer than its estimated duration, the situation does not immediatelybecome critical. Therefore, if a job has not started and the critical start timeis only a few minutes away, the timely completion of the critical job isconsidered to be potentially at risk.

The approachingLateOffset option allows you to determine the length of timebefore the critical start time of a job in the critical network at which youare to alerted to this potential risk. If a job has still not started the specifiednumber of seconds before the critical start time, the job is added to a hotlist that can be viewed on the Dynamic Workload Console.

Note: To qualify for addition to the hot list, all time and followdependencies must have been resolved.

This option is only active if enWorkloadServiceAssurance is set to yes.

The default is 120 seconds.

Note: Whatever value you set for this option, if Tivoli Workload Schedulerloses the connection with its database, the default value is applied tocritical job processing, and the warning message AWSJCO135W isissued to tell you what has happened.

Run JnextPlan or restart the WebSphere Application Server (stopappserverand startappserver) to make this change effective.

auditHistory | ahAudit history period. Used in audit management. Enter the number ofdays for which you want to save audit record data. Audit records arediscarded on a FIFO (first-in first-out) basis.

The default value is 180 days. This option takes effect immediately.

auditStore | asType of store to be used to log database audit records. Enter one of thefollowing:

file To specify that a flat file in the TWA_home/TWS/audit/databasedirectory is used to store the audit records (the default value).

db To specify that the Tivoli Workload Scheduler database itself isused to store the audit records.

both To have audit records logged in both the file and the database.


Any change of this value is effective immediately.

baseRecPrompt | bpMaximum prompts after abend. Specify the maximum number of promptsthat can be displayed to the operator after a job abends.

The default value is 1000. Run JnextPlan to make this change effective.

bindUser | buUser for binding to remote jobs from shadow job. Specify the user IDthat is used to bind a shadow job to a remote job during the security checkfor "cross dependencies". This user must be given at least the followingauthorizations in the security file:v Display access to the job and schedule objects that need to be boundv List access to job objects that need to be bound

However, the ID does not need to be in the user registry of the engine, norhave a password, as it is only required for authorization purposes.

The default value is the TWS_user. Any change of this value is effectiveimmediately.

carryStates | csCarry job states. A preproduction option that affects the operation of thestageman command. Specify the jobs, by state, to be included in job streamsthat are carried forward. Enclose the job states in parentheses, doublequotation marks, or single quotation marks. Commas can be replaced byspaces. The valid internal job states are as follows:

abend abenp add bound done error execfail hold intro pend ready rjob schedskel succ succp susp wait waitd

Some examples of the option are as follows:carryStates="abend,exec,hold,intro"carryStates=’abend,exec,hold,intro’carryStates="abend, exec, hold, intro"carryStates=’abend, exec, hold, intro’

An empty list is entered as follows:carryStates=null

The default value is null, which corresponds to selecting all states. RunJnextPlan to make this change effective.

companyName | cnCompany name. Specify the name of your company. The maximum lengthis 40 bytes. If the name contains spaces, enclose the name in quotationmarks ("). If you use the Japanese-Katakana language set, enclose the namewithin single or double quotation marks.

Run JnextPlan to make this change effective.

deadlineOffset | doDeadline offset. Used in workload service assurance. Used to calculate thecritical start of a critical job in the case where a deadline has not beenspecified neither for the job nor its job stream. In this case the deadline isdefaulted to the plan end date and time, plus this offset, expressed inminutes.



||

The default is 2 minutes.

Note:

1. Important: When the plan is extended, the start time of criticaljobs with a deadline calculated with this mechanism isautomatically changed as a consequence of the fact that it mustnow match the new plan finishing time.

2. Whatever value you set for this option, if Tivoli WorkloadScheduler loses the connection with its database, the defaultvalue is applied to critical job processing, and the warningmessage AWSJCO135W is issued to tell you what has happened.


deploymentFrequency | dfRules deployment frequency. Used in event rule management. Specify thefrequency, in minutes, with which rules are to be checked to detect if thereare changes to deploy. All active rules (active rules have the isDraftproperty set to no in their definition) that have been changed or addedsince the last deployment are deployed.

Valid values are in the 0-60 minutes range. If you specify 0, the changesare not deployed automatically and you must use the planman deploycommand.

The default value is 5 minutes. The change is effective immediately.

enCarryForward | cfEnable carry forward. A preproduction option that affects the operation ofthe stageman command. Specify if job streams that did not complete arecarried forward from the old to the new production plan (Symphony).Enter yes to have incompleted job streams carried forward only if theCarry Forward option is enabled in the job stream definition. Enter all tohave all incompleted job streams carried forward, regardless of the CarryForward option. Enter no to completely disable the Carry Forward function.If you run the JnextPlan -for 0000 command and the Carry Forwardoption is set to either yes or no, a message is displayed informing you thatincompleted job streams might not be carried forward. When the stageman-carryforward command is used, it overrides enCarryForward. See TivoliWorkload Scheduler: User's Guide and Reference for more information. If thisoption is set to no, running jobs are moved to the USERJOBS job stream.

The default value is all. Run JnextPlan to make this change effective.

enCentSec | tsEnable centralized security. Determine how the security file is used withinthe network. Centralized security is not relevant to an end-to-endscheduling environment.

If set to yes, the security files of all the workstations of the network can becreated and modified only on the master domain manager. In this case, theTivoli Workload Scheduler administrator is responsible for theirproduction, maintenance, and distribution.

If set to no, the security file of each workstation can be managed by theroot user or administrator of the system. The local user can run the makeseccommand to create or update the file.


||||||||||||||

|

See Tivoli Workload Scheduler: User's Guide and Reference for moreinformation about centralized security.

The default value is no. Run JnextPlan to make this change effective.

enCFinterNetworkDeps | ciEnable carry forward for internetwork dependencies. A preproductionoption that affects the way stageman handles internetwork dependencies. Itspecifies if external job streams are carried forward from the old to thenew production plan (Symphony file). Enter yes to have all external jobstreams carried forward. Enter no to have no external job streams carriedforward.

The default value is yes. Run JnextPlan to make this change effective.

enCFResourceQuantity | rqEnable carry forward resource quantity. A preproduction option thataffects the way stageman handles resources. Enter yes to carry forward theresource quantity from the old production file to the new. Enter no to notcarry forward the resource quantity. Stageman carries forward resourcequantities only if the resource is needed by a job or job stream that is alsobeing carried forward. Otherwise the resource quantities are set to theoriginal value. See Tivoli Workload Scheduler: User's Guide and Reference fordetails on using this feature.


enDbAudit | daEnable database auditing. Enable or disable database auditing. To disabledatabase auditing, specify 0. To activate database auditing, specify 1.Auditing information is logged to a flat file in the TWA_home/TWS/audit/database directory, to the Tivoli Workload Scheduler database itself, or toboth. To choose which, set the optman property auditStore. Each TivoliWorkload Scheduler workstation maintains its own log. Only actions arelogged, not the success or failure of the action. Installation of dynamicdomain managers and dynamic agents is not recorded in audit logs.

For more information about using this feature, see the section aboutauditing facilities in the Troubleshooting Guide.

The default value is 0. Changes to this parameter are effective immediately.

enEmptySchedsAreSucc | esJob streams without jobs policy. Specify the behavior of job streamswithout any jobs. If set to yes, the job streams that contain no jobs are setto SUCC after their dependencies are resolved. If set to no, the job streamsare left in READY status.


enEventDrivenWorkloadAutomation | edEnable event driven workload automation. Enable or disable theevent-driven workload automation feature. To enable, specify yes. Todisable, specify no.

The default value is yes.

After disabling, you must run JnextPlan and stop the event processingserver (with the conman stopevtp command).

After enabling, you must run JnextPlan and start the event processingserver (with the conman startevtp command).


|||||||||

||

|

enEventProcessorHttpsProtocol | ehEnable event processor HTTPS protocol. Used in event rule management.Enables or disables the use of the HTTPS protocol to connect to the eventprocessor server. To enable, enter yes. To disable, enter no.


enExpandedResourcesenExpandedResources Enables up to 60 concurrent holders for a TivoliWorkload Scheduler resource. Enter yes to enable up to 60 concurrentholders for a resource. Enter no to disable the feature and use only 32holders for a resource.


enForecastStartTime | stEnable forecast start time. Only applicable when workload serviceassurance is enabled (see enWorkloadServiceAssurance). Enter yes to enablethe calculation of the predicted start time of each job when running aforecast plan. Enabling this feature could negatively impact the time takento generate the forecast plan. Enter no to disable the calculation of thepredicted start time of each job when running a forecast plan.

The default value is no. Any change of this value is effective immediately.

When this option is set to yes, the enPreventStart global option is ignoredduring the creation of forecast plans.

enLegacyId | liEnable previous job stream ID. Determine how job streams are to benamed when operating in mixed environments with versions of TivoliWorkload Scheduler older than version 8.3, managed by a version 8.5master domain manager. Use this option to keep consistency in identifyingthe job streams in the plan. The value assigned to this option is read eitherwhen the production plan is created or extended, or when submitting jobstreams in production using conman.

When the plan is created or extended, if this option is set to no, the jobstream instance is assigned a new ID following the normal mechanism ofTivoli Workload Scheduler. In the Symphony file, the job stream name isequal to this ID. If the option is set to yes, the job stream instance isassigned an ID (symphony ID) equal to the job stream name. In theSymphony file the job stream name is equal to the real job stream name. Ifmore instances of the same job stream are present, an ID is generated forevery instance, with an alias that starts with the job stream name.


enLegacyStartOfDayEvaluation | leEvaluate start-of-day. Specify how the startOfDay option is to be managedacross the Tivoli Workload Scheduler network. If you set this option to yes,the startOfDay value on the master domain manager is converted to thelocal time zone set on each workstation across the network. If you set thisoption to no, the startOfDay value on the master domain manager isapplied as is on each workstation across the network. This option requiresthat the enTimeZone option is set to yes to become operational.


enListSecChk | scEnable list security check. Control the objects in the plan that a user ispermitted to list when running a query on the Dynamic Workload Console


|||||

|

or a conman show <object> command. If set to yes, objects in the planreturned from a query or show command are shown to the user only if theuser has been granted the list permission in the security file. If set to no, allobjects are shown, regardless of the settings in the security file.

Note: Setting this option to yes affects how the graphical user interfacesfunction for the users defined in the security file.

The default value is no. Run JnextPlan to make this change effective forthe plan. For the database, this option takes immediate effect.

enLogonBatch | lbAutomatically grant logon as batch. This is for Windows jobs only. If setto yes, the logon users for Windows jobs are automatically granted theright to Logon as batch job. If set to no, or omitted, the right must be grantedmanually to each user or group. The right cannot be granted automaticallyfor users running jobs on a Backup Domain Controller, so you must grantthose rights manually.


enPlanAudit | paEnable plan auditing. Enable or disable plan auditing. To enable planauditing, specify 1. To disable plan auditing, specify 0. Auditinginformation is logged to a flat file in the TWA_home/TWS/audit/plandirectory. Each Tivoli Workload Scheduler workstation maintains its ownlog. For the plan, only actions are logged in the auditing file, not thesuccess or failure of any action. See Tivoli Workload Scheduler: User's Guideand Reference for more information on this feature.


enPreventStart | psPrevent job stream without "at" dependency from starting. Specify if jobstreams without an at dependency are to be prevented from startingimmediately, without waiting for the run cycle specified in the job stream.Valid values are yes and no.


When the enForecastStartTime option is set to yes, this option is ignoredduring the creation of forecast plans.

enRetainNameOnRerunFrom | rrRetain rerun job name. A production option that affects the operation ofBatchman, the production control process of Tivoli Workload Scheduler. Itssetting determines if jobs that are rerun with the Conman rerun commandretain their original job names. To have rerun jobs retain their original jobnames, enter yes. Enter no to assign the rerun from name to rerun jobs.

The default values is no. Run JnextPlan to make this change effective.

enSSLFullConnection | sfEnable the SSL full connection. Specify that Tivoli Workload Scheduleruses a higher level of SSL connection than the standard level. For fulldetails see “Configuring full SSL security” on page 189. Valid values areyes to enable the SSL full connection or no to disable the SSL fullconnection.



enStrEncrypt | seEnable strong password encryption. Enable or disable strong encryption.Enable strong encryption by setting this option to yes. See “Configuring theSSL connection protocol for the network” on page 188.


enSwfaultTol | swEnable the fault-tolerant switch manager. Enable or disable thefault-tolerant switch manager feature. Valid values are yes to enable thefault tolerant switch manager, and no to disable it. See the Tivoli WorkloadScheduler: User's Guide and Reference for more details.


enTimeZone | tzEnable time zones. Enables or disables the time zone option. To activatetime zones in your network, specify yes. To disable time zones in thenetwork, specify no. See “Enabling the time zone feature” on page 75.

The default value is yes. Run JnextPlan to make this change effective inthe plan. For the database, this option takes effect immediately.

enWorkloadServiceAssurance | waEnable workload service assurance. Enables or disables workload serviceassurance, which is the feature that manages the privileged processing ofmission critical jobs and their predecessors. Specify yes to enable or no todisable.

Note: Before starting to use workload service assurance you must set upthe TWS_user in the security file to have the appropriate access tothe objects that this feature will modify - see “The TWS_user -special security file considerations” on page 133


eventProcessorEIFPort | eeTivoli event integration facility port. Used in event rule management.Specify the port number where the event processor server receives eventsfrom the Tivoli Event Integration Facility (EIF). Valid values are in the0-65535 range.

The default value is 31131. If you change the value, restart the WebSphereApplication Server (stopappserver and startappserver) and run JnextPlanto make this change effective.

If you use a security firewall, make sure this port is open for incoming andoutgoing connections.

extRecPrompt | xpAdditional prompts after abend. Specify an additional number of promptsfor the value defined in baseRecPropmt. This applies when a job is rerunafter abending and the limit specified in baseRecPropmt has been reached.


ignoreCals | icIgnore calendars. A preproduction option that affects the operation of theplanman command. Its setting determines if user calendars are copied intothe new production plan (Symphony) file. To prevent user calendars frombeing copied into the new production plan, enter yes.


The default value is no. See Tivoli Workload Scheduler: User's Guide andReference. Run JnextPlan to make this change effective.

logCleanupFrequency | lcLog cleanup frequency. Used in event rule and audit management .Specify how often the automatic cleanup of log instances is run. Validvalues are in the 0-60 minutes range. If you specify 0, the automaticcleanup feature is disabled.

The default value is 5 minutes. This option takes effect immediately.

logHistory | lhLog history period. Used in event rule management. Enter the number ofdays for which you want to save rule instance, action run, and message logdata. Log instances are discarded on a FIFO (first-in first-out) basis.

The default value is 10 days. This option takes effect immediately.

logmanMinMaxPolicy | lmLogman minimum and maximum run times policy. Specify how theminimum and maximum job run times are logged and reported by logman.Possible values are:

elapsedtimeThe minimum and maximum elapsed runtimes are logged andreported.

cputimeThe minimum and maximum CPU runtimes are logged andreported.

both Both the minimum and maximum job runtimes are logged andreported.

See Tivoli Workload Scheduler: User's Guide and Reference for details on usingthis feature.

The default value is both. Run JnextPlan to make this change effective.

logmanSmoothPolicy | ltLogman normal run time calculation policy. Set the weighting factor thatfavors the most recent job run when calculating the normal (average) runtime for a job. This is expressed as a percentage. For example, specify 40 toapply a weighting factor of 40% to the most recent job run, and 60% to theexisting average. See Tivoli Workload Scheduler: User's Guide and Reference formore information about how to use this option.

The default value is -1. Run JnextPlan to make this change effective.

longDurationThreshold | ldLong duration job threshold. Specify, when comparing the actual durationof a job to the estimated duration, the threshold over which the job isconsidered to be of "long duration." The threshold value is expressed as apercentage with respect to the estimated duration. For example, if thethreshold is set to 150, and the actual duration is more than 150% of theestimated duration (it is 50% greater), the job is considered to be a "longduration" job.

If you have the workload service assurance feature enabled, the effect of a"critical" job satisfying the long duration criteria is that the job is insertedautomatically into the hot list.


Valid values are between:100 The minimum value. All jobs that exceed the estimated duration

are considered long duration jobs1000 The maximum value. Only those jobs that last ten times as long as

their estimated duration are considered as long duration jobs


Note: Whatever value you set for this option, if you have the workloadservice assurance feature enabled, and Tivoli Workload Schedulerloses the connection with its database, the default value is applied tocritical job processing, and the warning message AWSJCO135W isissued to tell you what has happened.


mailSenderName | msMail sender name. Used in event rule management. If you deploy rulesimplementing an action that sends emails via an SMTP server, specify astring to be used as the sender of the emails.

The default value is TWS. Changes to this parameter are effective for thenext mail send action performed.

maxLen | xlMaximum preproduction plan length. Specify the maximum length of thepreproduction plan in days after it is automatically extended or created.The value for maxLen must be greater than or equal to the value for minLenand must be in the range of 8 to 365.

The default is 8 days. Run JnextPlan to make this change effective.

minLen | mlMinimum preproduction plan length. Specify the minimum length indays of the preproduction plan that can pass after the production plan iscreated or extended, without extending the preproduction plan. If the daysleft in the preproduction plan after a JnextPlan are less than the value ofthis option, the preproduction plan is automatically extended. The valuefor minLen must be less than or equal to the value for maxLen and must bein the range of 7 to 365.

The default is 8 days. Run JnextPlan to make this change effective.

notificationTimeout | ntNotification timeout. Used in cross dependencies. Specify how many daysTivoli Workload Scheduler must retry sending notifications about job statuschanges to the remote engine if the notification fails. When this timeoutexpires, the job request subscription and the status notifications associatedto this job are discarded.

Valid values are in the range of 1 to 90. The default is 5 days. Changes areeffective immediately.

promotionOffset | poPromotion offset. Used in workload service assurance. Specify when a jobbecome eligible for promotion in terms of the number of seconds before itscritical start time is reached. Applies only to jobs that are flagged as criticalin a job stream definition and to their predecessor jobs. A critical job andits predecessors make up a critical network.


||||||

||

When a predecessor jeopardizes the timely completion of the critical job, itis promoted; that is, it is assigned additional resources and its submission isprioritized with respect to other jobs that are out of the critical network.Also critical jobs might be promoted.

The scheduler calculates the critical start time of a critical job bysubtracting its estimated duration from its deadline. It calculates the criticalstart time of a critical predecessor by subtracting its estimated durationfrom the critical start time of its next successor. Within a critical networkthe scheduler calculates the critical start time of the critical job first andthen works backwards along the chain of predecessors. These calculationsare reiterated as many times as necessary until the critical job has run.



Run JnextPlan to make this change effective.

smtpServerName | snSMTP server name. Used in event rule management. If you deploy rulesimplementing an action that sends emails via an SMTP server, specify thename of the SMTP server to be used by the mail plug-in.

The default value is localhost. Changes to this parameter are effectiveimmediately.

smtpServerPort | spSMTP Server port. Used in event rule management. If you deploy rulesimplementing an action that sends emails via an SMTP server, specify theport number used to connect to the SMTP server by the mail plug-in. Validvalues are in the range 0–65535.

The default value is 25. Changes to this parameter are effective for the nextmail send action performed.

smtpUseAuthentication | uaMail plug-in uses SMTP authentication. Used in event rule management.If you deploy rules implementing an action that sends emails via an SMTPserver, specify if the SMTP connection needs to be authenticated. Valuesare yes or no.

The default is no. Changes to this parameter are effective immediately.

smtpUserName | unSMTP server user name. Used in event rule management. If you deployrules implementing an action that sends emails via an SMTP server, specifythe SMTP server user name.

The default value is the name of the Tivoli Workload Scheduler user (theTWS_user) on the master domain manager. Changes to this parameter areeffective immediately.

smtpUserPassword | upSMTP server user password. Used in event rule management. If youdeploy rules implementing an action that sends emails via an SMTP server,specify the SMTP server user password. The password is stored in anencrypted form.

Changes to this parameter are effective immediately.

smtpUseSSL | usMail plug-in uses SSL. Used in event rule management. If you deploy


rules implementing an action that sends emails via an SMTP server, specifyif the SMTP connection is to be authenticated via SSL. Values are yes or no.


smtpUseTLS | tlMail plug-in uses TLS protocol. Used in event rule management. If youdeploy rules implementing an action that sends emails via an SMTP server,specify if the SMTP connection is to be authenticated via the TransportLayer Security (TLS) protocol. Values are yes or no.


startOfDay | sdStart time of processing day. Specify the start time of the Tivoli WorkloadScheduler processing day in 24-hour format: hhmm (0000-2359).

The default value is 0600 (6:00 a.m.). If you change this option, you mustalso change the launch time of the final job stream, which is usually set toone minute before the start time: 0559 (5:59 a.m.). Run JnextPlan to makethe change of startOfDay effective.

statsHistory | shJob statistics history period. Specify the number of days for which youwant to maintain job statistics. Statistics are discarded on a FIFO (first-infirst-out) basis. For example, if you leave the default value of 10, statisticsare maintained for the last 10 days. This has no effect on job standard listfiles, which must be removed with the rmstdlist command. See the TivoliWorkload Scheduler: User's Guide and Reference for information about thermstdlist command.

The default value is 10. Run JnextPlan to make this change effective in theplan. For the database, this option takes effect immediately.

TECServerName | thTivoli Enterprise Console server name. Used in event rule management. Ifyou use rules implementing an action that forwards events to a TivoliEnterprise Console server (or any other application that can process eventsin Tivoli Enterprise Console format), specify the Tivoli Enterprise Consoleserver name. You can change this value when you define the action if youwant to use a different Tivoli Enterprise Console server.

The default is localhost. Run JnextPlan to make this change effective.

TECServerPort | tpTivoli Enterprise Console server port. Used in event rule management. Ifyou use rules implementing an action that forwards events to a TivoliEnterprise Console (TEC) server (or any other application that can processevents in TEC format), specify the port number of the TEC server. You canchange this value when you define the action if you want to use a differentTEC server.

The default port number is 5529. Run JnextPlan to make this changeeffective.

Setting local optionsSet local options in the localopts file. Changes do not take effect until netman isstopped (conman shut;wait) and restarted (StartUp).


A template file containing default settings is located in TWA_home/TWS/config/localopts.

Note: All of the SSL settings in the localopts file relate to the networkcommunications and do not relate to the Dynamic Workload Console.

During the installation process, a working copy of the local options file is installedas TWA_home/TWS/localopts.

The options in the localopts file are described in the following sections:v “Localopts summary”v “Localopts details” on page 26v “Local options file example” on page 38

Localopts summaryGeneral attributes of the workstation:

thiscpu = workstationmerge stdlists = yes|nostdlist width = columnssyslog local = facilityrestricted stdlists = yes|no

The attributes of the workstation for the batchman process:

bm check file = secondsbm check status = secondsbm look = secondsbm read = secondsbm stats = on|offbm verbose = on|offbm check until = secondsbm check deadline = secondsbm late every = minutes

The attributes of the workstation for the jobman process:

jm job table size = entriesjm look = secondsjm nice = valuejm promoted nice = UNIX and Linux critical job priorityjm promoted priority = Windows critical job priorityjm no root = yes|nojm read = seconds

The attributes of the workstation for the mailman process:

mm response = secondsmm retrylink = secondsmm sound off = yes|nomm unlink = secondsmm cache mailbox = yes|nomm cache size = bytesmm resolve master = yes|noautostart monman = yes|nomm read = minutes


|

|||||||||

The attributes of the workstation for the netman process:

nm mortal = yes|nonm port = port numbernm read = secondsnm retry = seconds

The attributes of the workstation for the writer process:

wr read = secondswr unlink = secondswr enable compression = yes|no

Optional attributes of the workstation for remote database files

mozart directory = mozart_shareparameters directory = parms_shareunison network directory = unison_share

The attributes of the workstation for the custom formats

date format = integercomposer prompt = keyconman prompt = keyswitch sym prompt = key

The attributes of the workstation for the customization of I/O on mailbox files

sync level = low|medium|high

The attributes of the workstation for networking

tcp timeout = secondstcp connection timeout = seconds

The attributes of the workstation for SSL - General

ssl auth mode = caonly|string|cpussl auth string = stringssl fips enabled = yes/nonm ssl full port = valuenm ssl port = value

OpenSSL attributes of the workstation - only used if ssl fips enabled = "no"

ssl key = *.pemssl certificate = *.pemssl key pwd = *.sthssl ca certificate = *.crtssl random seed = *.rndssl encryption cipher = ciphercli ssl server auth = yes|nocli ssl cipher = stringcli ssl server certificate = file_namecli ssl trusted dir = directory_name

GSKit attributes of the workstation - only used if ssl fips enabled = "yes"

ssl keystore file = *.kdbssl certificate keystore label = name


|

ssl keystore pwd = *.sthcli ssl keystore file = *.kdbcli ssl certificate keystore label = namecli ssl keystore pwd = *.sth

The attributes of the workstation for the embedded WebSphere ApplicationServer

local was = yes|no

Application server check attributes on the workstation

appserver check interval = minutesappserver auto restart = on|offappserver min restart time = minutesappserver max restarts = numberappserver count reset interval = hoursappserver service name = name

The Tivoli Workload Scheduler instance is a command line client

is remote cli = yes|no

Attributes for command line client connection (conman)

host = host_nameprotocol = protocolport = port numberproxy = proxy serverproxy port = proxy server port numbertime out = secondsdefault ws = master_workstationuseropts = useropts_file

Note: The SSL attributes for the command line client connection willdepend on which SSL method is in use. They are included in therelevant section and all commence with "cli".

Event Management parameters

can be event processor = yes|no

Note: The localopts file syntax is not case-sensitive, and the spaces betweenwords in the option names are ignored. For example, you can validly writeis remote cli as:v is remote cliv Is Remote CLIv isremotecliv ISREMOTECLIv isRemoteCLIv ...

Localopts details# comment

Treats everything from the indicated sign (#) to the end of the line as acomment.


appserver auto restart = yes|noRequests the appservman process to automatically start WebSphereApplication Server if it is found down. The default is Yes.

appserver check interval = minutesSpecifies the frequency in minutes that the appservman process is to checkthat WebSphere Application Server is still running. The default is 5minutes.

appserver count reset interval = hoursSpecifies the time interval in hours after which the restart count is resetfrom the last WebSphere Application Server start. The default is 24 hours.

appserver max restarts = numberSpecifies the maximum number of restarting attempts the appservmanprocess can make before giving up and exiting without restartingWebSphere Application Server. The counter is reset if WebSphereApplication Server runs for longer than the appserver count resetinterval value. The default is 5.

appserver min restart time = minutesSpecifies in minutes the minimum elapsed time the appservman processmust wait between each attempt to restart the WebSphere ApplicationServer if it is down. If this value is less than the appserver checkinterval, the WebSphere Application Server is restarted as soon as it isfound down. If it is found down before this time interval (min restart time)has elapsed, appservman exits without restarting it. The default is 10minutes.

appserver service name = nameOnly in Windows environments. Specifies the name of the WebSphereApplication Server windows service if different from the standard name.This field is generally not used.

autostart monman = yes|noUsed in event rule management. Restarts the monitoring engineautomatically when the next production plan is activated (on Windowsalso when Tivoli Workload Scheduler is restarted). The default is Yes.

bm check deadline = secondsSpecify the minimum number of seconds Batchman waits before checkingif a job has missed its deadline. The check is performed on all jobs and jobstreams included in the Symphony file, regardless of the workstationwhere the jobs and job streams are defined. Jobs and job streams withexpired deadlines are marked as late in the local Symphony file. To obtainup-to-date information about the whole environment, define this option onthe master domain manager. Deadlines for critical jobs are evaluatedautomatically, independently of the bm check deadline option. To disablethe option and not check deadlines, enter a value of zero, the defaultvalue.

bm check file = secondsSpecify the minimum number of seconds Batchman waits before checkingfor the existence of a file that is used as a dependency. The default is 120seconds.

bm check status = secondsSpecify the number of seconds Batchman waits between checking thestatus of an internetwork dependency. The default is 300 seconds.


|||||||||||

bm check until = secondsSpecify the maximum number of seconds Batchman waits before reportingthe expiration of an Until time for job or job stream. Specifying a valuebelow the default setting (300) might overload the system. If it is set belowthe value of Local Option bm read, the value of bm read is used in itsplace. The default is 300 seconds.

bm look = secondsSpecify the minimum number of seconds Batchman waits before scanningand updating its production control file. The default is 15 seconds.

bm read = secondsSpecify the maximum number of seconds Batchman waits for a message inthe intercom.msg message file. If no messages are in queue, Batchmanwaits until the timeout expires or until a message is written to the file. Thedefault is 10 seconds.

bm stats = on|offTo have Batchman send its startup and shutdown statistics to its standardlist file, specify on. To prevent Batchman statistics from being sent to itsstandard list file, specify off. The default is off.

bm verbose = on|offTo have Batchman send all job status messages to its standard list file,specify on. To prevent the extended set of job status messages from beingsent to the standard list file, specify off. The default is off.

bm late every = minutesWhen an every job does not start at its expected start time, bm late everyspecifies the maximum number of minutes that elapse before TivoliWorkload Scheduler skips the job. This option applies only to jobs definedwith every option together with the at time dependency, it has no impacton jobs that have only the every option.

can be event processor = yes|noSpecify if this workstation can act as event processing server or not. It isset by default to yes for master domain managers and backup masters,otherwise it is set to no.

cli ssl certificate keystore label = stringOnly used if SSL is defined using GSKit (ssl fips enabled="yes") Supplythe label which identifies the certificate in the keystore when thecommand-line client is using SSL authentication to communicate with themaster domain manager. The default is IBM TWS 8.6 workstation, which isthe value of the certificate distributed with the product to all customers.This certificate is thus not secure and should be replaced with your ownsecure certificate. See “Configuring the SSL connection protocol for thenetwork” on page 188.

cli ssl keystore file = file_nameOnly used if SSL is defined using GSKit (ssl fips enabled="yes"). Specifythe name of the keystore file used for SSL authentication when thecommand-line client is using SSL authentication to communicate with themaster domain manager. The default is TWA_home/TWS/ssl/TWSPublicKeyFile.pem. This file is part of the SSL configuration distributedwith the product to all customers. It is thus not secure and should bereplaced with your own secure SSL configuration. See “Configuring theSSL connection protocol for the network” on page 188.


||||||

cli ssl keystore pwd = file_nameOnly used if SSL is defined using GSKit (ssl fips enabled="yes"). Specifythe password file of the keystore used for SSL authentication when thecommand-line client is using SSL authentication to communicate with themaster domain manager. This file is part of the SSL configurationdistributed with the product to all customers. It is thus not secure andshould be replaced with your own secure SSL configuration. See“Configuring the SSL connection protocol for the network” on page 188.

cli ssl cipher = cipher_classOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Specify the cipher class to be used when the command-line client and theserver are using SSL authentication. Use one of the common cipher classeslisted in Table 12. The default is MD5.

If you want to use an OpenSSL cipher class not listed in the table, use thefollowing command to determine if your required class is supported:openssl ciphers <class_name>

where class_name is the name of the class you want to use. If the commandreturns a cipher string, the class can be used.

Table 12. Valid encryption cipher classes

Encryption cipher class Description

SSLv3 SSL version 3.0

TLSv1 TLS version 1.0

EXP Export

EXPORT40 40-bit export

MD5 Ciphers using the MD5 digest, digital signature,one-way encryption, hash or checksumalgorithm.

LOW Low strength (no export, single DES)

MEDIUM Ciphers with 128 bit encryption

HIGH Ciphers using Triple-DES

NULL Ciphers using no encryption

cli ssl server auth = yes|noOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Specify yes if server authentication is to be used in SSL communicationswith the command line client. The default is no.

cli ssl server certificate = file_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Specify the file that contains the SSL certificate when the command-lineclient and the server use SSL authentication in their communication. Thereis no default. See “Configuring the SSL connection protocol for thenetwork” on page 188.

cli ssl trusted dir = directory_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Specify the directory that contains an SSL trusted certificate contained infiles with hash naming (#) when the command-line client and the serverare using SSL authentication in their communication. When the directorypath contains blanks, enclose it in double quotation marks ("). There is nodefault.


composer prompt = promptSpecify the prompt for the composer command line. The prompt can be ofup to 10 characters in length. The default is dash (-).

conman prompt = promptSpecify the prompt for the conman command line. The prompt can be ofup to 8 characters in length. The default is percent (%).

date format = 0|1|2|3Specify the value that corresponds to the date format you desire. Thevalues can be:v 0 corresponds to yy/mm/dd

v 1 corresponds to mm/dd/yy

v 2 corresponds to dd/mm/yy

v 3 indicates usage of Native Language Support variables

The default is 1.

default ws = manager_workstationThe default workstation when you are accessing using a command lineclient. Specify the domain manager workstation.

host = hostname_or_IP_addressThe name or IP address of the host when accessing using a command lineclient.

is remote cli = yes|noSpecify if this instance of Tivoli Workload Scheduler is installed as acommand line client (yes).

jm job table size = entriesSpecify the size, in number of entries, of the job table used by Jobman. Thedefault is 1024 entries.

jm look = secondsSpecify the minimum number of seconds Jobman waits before looking forcompleted jobs and performing general job management tasks. The defaultis 300 seconds.

jm nice = nice_valueFor UNIX and Linux operating systems only, specify the nice value to beapplied to jobs launched by Jobman to change their priority in the kernel'sscheduler. The default is zero.

The nice boundary values vary depending upon each specific platform, butgenerally lower values correspond to higher priority levels and vice versa.The default depends upon the operating system.

Applies to jobs scheduled by the root user only. Jobs submitted by anyother user inherit the same nice value of the Jobman process.

See also jm promoted nice.

jm no root = yes|noFor UNIX and Linux operating systems only, specify yes to preventJobman from launching root jobs. Specify no to allow Jobman to launchroot jobs. The default is no.

jm promoted nice = nice_valueUsed in workload service assurance. For UNIX and Linux operatingsystems only, assigns the priority value to a critical job that needs to be


promoted so that the operating system processes it before others. Appliesto critical jobs or predecessors that need to be promoted so that they canstart at their critical start time.

Boundary values vary depending upon each specific platform, butgenerally lower values correspond to higher priority levels and vice versa.The default is -1.

Be aware that:v The promotion process is effective with negative values only. If you set a

positive value, the system runs it with the -1 default value and logs awarning message every time Jobman starts.

v An out of range value (for example -200), prompts the operating systemto automatically promote the jobs with the lowest allowed nice value.Note that in this case no warning is logged.

v Overusing the promotion mechanism (that is, defining an exceedinglyhigh number of jobs as mission critical and setting the highest priorityvalue here) might overload the operating system, negatively impactingthe overall performance of the workstation.

You can use this and the jm nice options together. If you do, rememberthat, while jm nice applies only to jobs submitted by the root user, jmpromoted nice applies only to jobs that have a critical start time. When ajob matches both conditions, the values set for the two options add up. Forexample, if on a particular agent the local options file has:jm nice= -2jm promoted nice= -4

when a critical job submitted by the root user needs to be promoted, it isassigned a cumulative priority value of -6.

jm promoted priority = valueUsed in workload service assurance. For Windows operating systems only,sets to this value the priority by which the operating system processes acritical job when it is promoted.

Applies to critical jobs or predecessors that need to be promoted so thatthey can start at their critical start time.

The possible values are:v High

v AboveNormal (the default)v Normal

v BelowNormal

v Low or Idle

Note that if you a set a lower priority value than the one non-critical jobsmight be assigned, no warning is given and no mechanism like the oneavailable for jm promoted nice sets it back to the default.

jm read = secondsSpecify the maximum number of seconds Jobman waits for a message inthe courier.msg message file. The default is 10 seconds.

local was = yes|noFor master domain managers and backup masters connected to the TivoliWorkload Scheduler database. If set to yes, it improves the performance ofjob stream and job submission from the database The default is no.


merge stdlists = yes|noSpecify yes to have all of the Tivoli Workload Scheduler control processes,except Netman, send their console messages to a single standard list file.The file is given the name TWSmerge. Specify no to have the processessend messages to separate standard list files. The default is yes.

mm cache mailbox = yes|noUse this option to enable Mailman to use a reading cache for incomingmessages. In this case, only messages considered essential for networkconsistency are cached. The default is yes.

mm cache size = messagesSpecify this option if you also use mm cache mailbox. The maximumvalue (default) is 512.

mm read = secondsSpecify the maximum number of seconds Mailman waits for a connectionwith a remote workstation. The default is 15 seconds.

mm resolve master = yes|noWhen set to yes the $MASTER variable is resolved at the beginning of theproduction day. The host of any extended agent is switched after the nextJnextPlan (long term switch). When it is set to no, the $MASTER variableis not resolved at JnextPlan and the host of any extended agent can beswitched after a conman switchmgr command (short- and long-termswitch). The default is yes. When you switch a master domain managerand the original has mm resolve master set to no and the backup has mmresolve master set to yes, after the switch any extended agent that ishosted by $MASTER switches to the backup domain manager. When thebackup domain manager restarts, the keyword $MASTER is locallyexpanded by Mailman. You should keep the mm resolve master value thesame for master domain managers and backup domain managers.

mm response = secondsSpecify the maximum number of seconds Mailman waits for a responsebefore reporting that a workstation is not responding. The minimum waittime for a response is 90 seconds. The default is 600 seconds.

mm retrylink = secondsSpecify the maximum number of seconds Mailman waits after unlinkingfrom a non-responding workstation before it attempts to link to theworkstation again. The default is 600 seconds. The tomserver optionalmailman servers do not unlink non-responding agents. The link isrepetitively checked every 60 seconds, which is the default retrylink forthese servers.

mm sound off = yes|noSpecify how Mailman responds to a conman tellop ? command. Specifyyes to have Mailman display information about every task it is performing.Specify no to have Mailman send only its own status. The default is no.

mm symphony download timeout = secondsSpecify the maximum number of minutes Mailman waits after attemptingto initialize a workstation on a slow network. If the timeout expireswithout the workstation being initialized successfully, Mailman initializesthe next workstation in the sequence. The default is no timeout (0).

mm unlink = secondsSpecify the maximum number of seconds Mailman waits before unlinking


|||||

from a workstation that is not responding. The wait time should not beless than the response time specified for the Local Option nm response.The default is 960 seconds.

mozart directory = directory_nameThis parameter applies only to versions of Tivoli Workload Scheduler priorto version 8.3. Defines the name of the master domain managers sharedmozart directory. The default is TWA_home/mozart.

nm mortal = yes|noSpecify yes to have Netman quit when all of its child processes havestopped. Specify no to have Netman keep running even after its childprocesses have stopped. The default is no.

nm port = portSpecify the TCP port number that Netman responds to on the localcomputer. This must match the TCP/IP port in the computers workstationdefinition. It must be an unsigned 16-bit value in the range 1- 65535(values between 0 and 1023 are reserved for services such as, FTP,TELNET, HTTP, and so on). The default is the value supplied during theproduct installation.

If you run event-driven workload automation and you have a securityfirewall, make sure this port is open for incoming and outgoingconnections.

nm read = secondsSpecify the maximum number of seconds Netman waits for a connectionrequest before checking its message queue for stop and start commands.The default is 10 seconds.

nm retry = secondsSpecify the maximum number of seconds Netman waits before retrying aconnection that failed. The default is 800 seconds.

nm ssl full port = portThe port used to listen for incoming SSL connections when full SSL isconfigured by setting global option enSSLFullConnection to yes (see“Configuring full SSL security” on page 189 for more details). This valuemust match the one defined in the secureaddr attribute in the workstationdefinition in the database. It must be different from the nm port localoption that defines the port used for normal communication.

Note:1. If you install multiple instances of Tivoli Workload Scheduler on

the same computer, set all SSL ports to different values.2. If you plan not to use SSL, set the value to 0.

There is no default.

nm ssl port = portThe port used to listen for incoming SSL connections, when full SSL is notconfigured (see “Configuring full SSL security” on page 189 for moredetails). This value must match the one defined in the secureaddr attributein the workstation definition in the database. It must be different from thenm port local option that defines the port used for normal communication.

Note:1. If you install multiple instances of Tivoli Workload Scheduler on

the same computer, set all SSL ports to different values.


2. If you plan not to use SSL, set the value to 0.

There is no default.

parameters directory = directory_nameThis parameter applies only to versions of Tivoli Workload Scheduler priorto version 8.3. Defines the name of the master domain managers sharedTWA_home directory. The default is none.

port = portThe TCP/IP port number of the protocol used when accessing using acommand line client. The default is 31115.

protocol = http|httpsThe protocol used to connect to the host when accessing using a commandline client.

proxy = proxy_server_hostname_or_IP_addressThe name of the proxy server used when accessing using a command lineclient.

proxy port = proxy_server_portThe TCP/IP port number of the proxy server used when accessing using acommand line client.

restricted stdlists = yes|noUse this option to set a higher degree of security to the stdlist directory(and to its subdirectories) allowing only selected users to create, modify, orread files.

This option is available for UNIX workstations only. After you define it,make sure you erase your current stdlist directory (and subdirectories)and that you restart Tivoli Workload Scheduler. The default is no.

If the option is not present or if it is set to no, the newly created stdlistdirectory and its subdirectories are unaffected and their rights are asfollows:drwxrwxr-x 22 twsmdm staff 4096 Nov 09 12:12drwxrwxr-x 2 twsmdm staff 256 Nov 09 11:40 2009.11.09drwxrwxr-x 2 twsmdm staff 4096 Nov 09 11:40 logsdrwxr-xr-x 2 twsmdm staff 4096 Nov 09 11:40 traces

If the option is set to yes, these directories have the following rights:drwxr-x--x 5 twsmdm staff 256 Nov 13 18:15rwxr-x--x 2 twsmdm staff 256 Nov 13 18:15 2009.11.13rwxr-x--x 2 twsmdm staff 256 Nov 13 18:15 logsrwxr-x--x 2 twsmdm staff 256 Nov 13 18:15 traces

Do the following to define and activate this option:1. Change the line restricted stdlists = no to restricted stdlists =

yes in your local options file.2. Stop Tivoli Workload Scheduler.3. Stop WebSphere Application Server if present.4. Remove the stdlist directory (or at least its files and subdirectories).5. Start Tivoli Workload Scheduler.6. Start WebSphere Application Server if present.

ssl auth mode = caonly|string|cpuThe behavior of Tivoli Workload Scheduler during an SSL handshake isbased on the value of the SSL authentication mode option as follows:

caonly Tivoli Workload Scheduler checks the validity of the certificate and


verifies that the peer certificate has been issued by a recognizedCA. Information contained in the certificate is not examined. Thedefault value.

string Tivoli Workload Scheduler checks the validity of the certificate andverifies that the peer certificate has been issued by a recognizedCA. It also verifies that the Common Name (CN) of the CertificateSubject matches the string specified into the SSL auth string option.See 35.

cpu Tivoli Workload Scheduler checks the validity of the certificate andverifies that the peer certificate has been issued by a recognizedCA. It also verifies that the Common Name (CN) of the CertificateSubject matches the name of the workstation that requested theservice.

ssl auth string = stringUsed in conjunction with the SSL auth mode option when the "string"value is specified. The SSL auth string (ranges from 1 — 64 characters) isused to verify the certificate validity. The default string is "tws".

ssl ca certificate = file_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Specify the name of the file containing the trusted certification authority(CA) certificates required for SSL authentication. The CAs in this file arealso used to build the list of acceptable client CAs passed to the clientwhen the server side of the connection requests a client certificate. This fileis the concatenation, in order of preference, of the various PEM-encodedCA certificate files.

The default is TWA_home/TWS/ssl/TWSTrustedCA.crt. This file is part of theSSL configuration distributed with the product to all customers. It is thusnot secure and should be replaced with your own secure SSLconfiguration. See “Configuring the SSL connection protocol for thenetwork” on page 188.

ssl certificate = file_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Specify the name of the local certificate file used in SSL communication.

The default is TWA_home/TWS/ssl/TWSPublicKeyFile.pem. This file is part ofthe SSL configuration distributed with the product to all customers. It isthus not secure and should be replaced with your own secure SSLconfiguration. See “Configuring the SSL connection protocol for thenetwork” on page 188.

ssl certificate keystore label = stringOnly used if SSL is defined using GSKit (ssl fips enabled="yes") Supplythe label which identifies the certificate in the keystore when using SSLauthentication.

The default is IBM TWS 8.6 workstation, which is the value of thecertificate distributed with the product to all customers. This certificate isthus not secure and should be replaced with your own secure certificate.See “Configuring the SSL connection protocol for the network” on page188.

ssl encryption cipher = cipher_classOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")Define the ciphers that the workstation supports during an SSL connection.


Use one of the common cipher classes listed in Table 12 on page 29. Thedefault is SSLv3. If you want to use an OpenSSL cipher class not listed inthe table, use the following command to determine if your required class issupported:openssl ciphers <class_name>

where class_name is the name of the class you want to use. If the commandreturns a cipher string, the class can be used.

ssl fips enabled = yes|noDetermines whether your entire Tivoli Workload Scheduler network isenabled for FIPS (Federal Information Processing Standards) compliance.FIPS compliance requires the use of GSKit instead of the default OpenSSLfor secure communications. If you enable FIPS (ssl fips enabled="yes") youmust set values for all the SSL attributes that apply to GSKit. If you do notenable FIPS (ssl fips enabled="no"), set the values for OpenSSL. The defaultis no. See “FIPS compliance” on page 201 for more details.

ssl key = file_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no") Thename of the private key file.

The default is TWA_home/TWS/ssl/TWSPrivateKeyFile.pem. This file is part ofthe SSL configuration distributed with the product to all customers. It isthus not secure and should be replaced with your own secure SSLconfiguration. See “Configuring the SSL connection protocol for thenetwork” on page 188.

ssl key pwd = file_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no") Thename of the file containing the password for the stashed key.

The default is TWA_home/TWS/ssl/TWSPrivateKeyFile.sth. This file is part ofthe SSL configuration distributed with the product to all customers. It isthus not secure and should be replaced with your own secure SSLconfiguration. See “Configuring the SSL connection protocol for thenetwork” on page 188.

ssl keystore file = file_nameOnly used if SSL is defined using GSKit (ssl fips enabled="yes"). Specifythe name of the keystore file used for SSL authentication.

The default is TWA_home/TWS/ssl/TWSKeyRing.kdb. This file is part of theSSL configuration distributed with the product to all customers. It is thusnot secure and should be replaced with your own secure SSLconfiguration. See “Configuring the SSL connection protocol for thenetwork” on page 188.

ssl keystore pwd = file_nameOnly used if SSL is defined using GSKit (ssl fips enabled="yes"). Specifythe name of the keystore password file used for SSL authentication.

The default is TWA_home/TWS/ssl/TWSKeyRing.sth. This file is part of theSSL configuration distributed with the product to all customers. It is thusnot secure and should be replaced with your own secure SSLconfiguration. See “Configuring the SSL connection protocol for thenetwork” on page 188.

ssl random seed = file_nameOnly used if SSL is defined using OpenSSL (ssl fips enabled="no")


Specify the pseudo random number file used by OpenSSL on someoperating systems. Without this file, SSL authentication might not workcorrectly.

The default is TWA_home/TWS/ssl/TWS.rnd. This file is part of the SSLconfiguration distributed with the product to all customers. It is thus notsecure and should be replaced with your own secure SSL configuration.See “Configuring the SSL connection protocol for the network” on page188.

stdlist width = columnsSpecify the maximum width of the Tivoli Workload Scheduler consolemessages. You can specify a column number in the range 1 to 255. Linesare wrapped at or before the specified column, depending on the presenceof imbedded carriage control characters. Specify a negative number or zeroto ignore line width. On UNIX and Linux operating systems, you shouldignore line width if you enable system logging with the syslog localoption. The default is 0 columns.

switch sym prompt = promptSpecify a prompt for the conman command line after you have selected adifferent Symphony file with the setsym command. The maximum lengthis 8 characters. The default is n%.

sync level = low|medium|highSpecify the rate at which Tivoli Workload Scheduler synchronizesinformation written to disk. This option affects all mailbox agents and isapplicable to UNIX and Linux operating systems only. Values can be:

low Allows the operating system to handle it.

mediumFlushes the updates to disk after a transaction has completed.

high Flushes the updates to disk every time data is entered.

The default is low.

syslog local = valueEnables or disables Tivoli Workload Scheduler system logging for UNIXand Linux operating systems only. Specify -1 to turn off system logging forTivoli Workload Scheduler. Specify a number from 0 to 7 to turn on systemlogging and have Tivoli Workload Scheduler use the corresponding localfacility (LOCAL0 through LOCAL7) for its messages. Specify any othernumber to turn on system logging and have Tivoli Workload Scheduler usethe USER facility for its messages. The default is -1. See “Tivoli WorkloadScheduler console messages and prompts” on page 73.

tcp connect timeout = secondsSpecify the maximum number of seconds that can be waited to establish aconnection through non-blocking socket. The default is 15 seconds.

tcp timeout = secondsSpecify the maximum number of seconds that can be waited for thecompletion of a request on a connected workstation that is not responding.The default is 300 seconds.

this cpu = workstation_nameSpecify the Tivoli Workload Scheduler name of this workstation. When aswitch is made between the master domain manager and a backup domain


manager, using the switchmgr command, the Symphony header value forthis cpu is overwritten by the this cpu value in the localopts file. Thedefault is $(this_cpu).

timeout = secondsThe timeout in seconds when accessing using a command line client. Thedefault is 3600 seconds.

unison network directory = directory_nameThis parameter applies only to versions of Tivoli Workload Scheduler priorto version 8.3. Defines the name of the Unison network directory. Thedefault is <TWA_home>/../unison/network.

useropts = file_nameIf you have multiple instances of Tivoli Workload Scheduler on a system,use this to identify the useropts file that is to be used to store theconnection parameters for the instance in which this localops file is found.See “Multiple product instances” on page 42 for more details.

wr enable compression = yes|noUse this option on fault-tolerant agents. Specify if the fault-tolerant agentcan receive the Symphony file in compressed form from the master domainmanager. The default is no.

wr read = secondsSpecify the number of seconds the Writer process waits for an incomingmessage before checking for a termination request from Netman. Thedefault is 600 seconds.

wr unlink = secondsSpecify the number of seconds the Writer process waits before exiting if noincoming messages are received. The minimum is 120 seconds. The defaultis 180 seconds.

Local options file example

The following is an example of a default localopts file:

Note: Some parameters might not be present depending upon your version andconfiguration.

############################################################################## Licensed Materials - Property of IBM(R)# 5698-WSH# (C) Copyright IBM Corp. 1991, 2011. All Rights Reserved# US Government Users 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.############################################################################### The Tivoli Workload Scheduler localopts file defines the attributes of this# workstation, for various processes.##----------------------------------------------------------------------------# General attributes of this workstation:#thiscpu =$(this_cpu)merge stdlists =yesstdlist width =0syslog local =-1restricted stdlists =no#


#----------------------------------------------------------------------------# The attributes of this workstation for the batchman process:#bm check file =120bm check status =300bm look =15bm read =10bm stats =offbm verbose =offbm check until =300bm check deadline =0##----------------------------------------------------------------------------# The attributes of this workstation for the jobman process:#jm job table size =1024jm look =300jm nice =0jm promoted nice =-1 #UNIXjm promoted priority =AboveNormal #WINDOWSjm no root =nojm read =10##----------------------------------------------------------------------------# The attributes of this workstation for the TWS mailman process:#mm response =600mm retrylink =600mm sound off =nomm unlink =960mm cache mailbox =yesmm cache size =512mm resolve master =yesautostart monman =yesmm read =15##----------------------------------------------------------------------------# The attributes of this workstation for the netman process:#nm mortal =nonm port =$(tcp_port)nm read =10nm retry =800##----------------------------------------------------------------------------# The attributes of this workstation for the writer process:#wr read =600wr unlink =180wr enable compression =no##----------------------------------------------------------------------------# Optional attributes of this Workstation for remote database files## mozart directory = $(install_dir)/mozart# parameters directory = $(install_dir)# unison network directory = $(install_dir)/../unison/network##----------------------------------------------------------------------------# The attributes of this workstation for custom formats#date format =1 # The possible values are 0-yyyy/mm/dd,

# 1-mm/dd/yyyy, 2-dd/mm/yyyy, 3-NLS.composer prompt =-conman prompt =%switch sym prompt =<n>%#


#----------------------------------------------------------------------------# The attributes of this workstation for the customization of I/O on# mailbox files#sync level =low##----------------------------------------------------------------------------# The attributes of this workstation for networking#tcp timeout =300tcp connection timeout =15##----------------------------------------------------------------------------# General Secure options#SSL auth mode =caonly## Use "SSL auth string" only if "SSL auth mode" is set to "string"#SSL auth string =tws## Supply "yes" for "SSL Fips enabled" to force TWS to use GSKIT,# otherwise it uses OpenSSL# This flag set to "yes" enables the FIPS 140-2 policies.# The default value is "no".#SSL Fips enabled = no## Netman full SSL port, use "nm SSL full port" if "enSSLFullConnection"# (Global Option) is set to "yes". The value "0" means the port is closed.#nm SSL full port =0## Netman SSL port# the value "0" means port close#nm SSL port =0## End General Secure options#----------------------------------------------------------------------------

#----------------------------------------------------------------------------# OpenSSL options, TWS uses them if "SSL Fips enabled" is "no" ( the default )#SSL key ="$(install_dir)/ssl/TWSPrivateKeyFile.pem"SSL certificate ="$(install_dir)/ssl/TWSPublicKeyFile.pem"SSL key pwd ="$(install_dir)/ssl/TWSPrivateKeyFile.sth"SSL CA certificate ="$(install_dir)/ssl/TWSTrustedCA.crt"SSL random seed ="$(install_dir)/ssl/TWS.rnd"SSL Encryption Cipher =SSLv3##CLI SSL server auth =#CLI SSL cipher = MD5#CLI SSL server certificate =#CLI SSL trusted dir =# End OpenSSL options#----------------------------------------------------------------------------

#----------------------------------------------------------------------------# GSKIT options, TWS uses them if "SSL Fips enabled" is "yes"##SSL keystore file = "$(install_dir)/ssl/TWSKeyRing.kdb"SSL certificate keystore label = "IBM TWS 8.6 workstation"SSL keystore pwd = "$(install_dir)/ssl/TWSKeyRing.sth"##CLI SSL keystore file = "$(install_dir)/ssl/TWSKeyRing.kdb"


CLI SSL certificate keystore label = "IBM TWS 8.6 workstation"CLI SSL keystore pwd = "$(install_dir)/ssl/TWSKeyRing.sth"#----------------------- End GSKit options ----------------------------------

#----------------------------------------------------------------------------# The attributes of this workstation for the embedded version of the# IBM WebSphere Application Server#LOCAL WAS =no##----------------------------------------------------------------------------# Application server check attributes

Appserver check interval = 5 #minutesAppserver auto restart = yes #yes/noAppserver min restart time = 10 #minutesAppserver max restarts = 5 #restarts numberAppserver count reset interval = 24 #hours#Appserver service name = "IBMWAS70Service - tws860xx"#----------------------------------------------------------------------------# The TWS instance has been installed as REMOTE CLIIS REMOTE CLI = no # yes for a REMOTE CLI installation, no otherwise

#----------------------------------------------------------------------------# Attributes for command-line client connections#host = # Master hostname used when attempting a connection.protocol = https # Protocol used to establish a connection with the Master.#protocol = http # Protocol used to establish a connection with the Master.port = # Protocol portproxy = # Hostname of proxy serverproxy port = # Port of proxy servertimeout = 3600 # Timeout in seconds to wait for a server responsedefault ws =useropts =## The SSL connection options are listed above under the relevant section for# the type of SSL you have implemented. They all have the prefix "cli" and# must also be provided.##----------------------------------------------------------------------------

Note: The "REMOTE CLI" refers to the command line client.

Setting user options

Set the user options you require for each user on a workstation who needs them inthe useropts file. Changes do not take effect until Tivoli Workload Scheduler isstopped and restarted.

The concept of the useropts file is to contain values for localopts parameters thatmust be personalized for an individual user. The files must be located in theuser_home/.TWS directory of the user. When Tivoli Workload Scheduler needs toaccess data from the localopts file, it looks first to see if the property it requires isstored only or also in the useropts file for the user, always preferring the useroptsfile version of the value of the key. If a property is not specified when invoking thecommand that requires it, or inside the useropts and localopts files, an error isdisplayed.

The main use of the useropts file is to store the user-specific connectionparameters used to access the command line client (see “Configuring


command-line client access authentication” on page 70). These are the followingkeys, which are not stored in the localopts file:

usernameUser name used to access the master domain manager. The user must bedefined in the security file on the master domain manager (see Chapter 4,“Configuring user authorization (Security file),” on page 101)

passwordPassword used to access the master domain manager. The presence of theENCRYPT label in the password field indicates that the specified setting hasbeen encrypted; if this label is not present, you must exit and access theinterface program again to allow the encryption of that field.

A useropts file is created for the <TWS_user> during the installation, but you mustcreate a separate file for each user that needs to use user-specific parameters on aworkstation.

Sample useropts file

This is the sample content of a useropts file:## Tivoli Workload Scheduler useropts file defines attributes of this Workstation.##----------------------------------------------------------------------------# Attributes for CLI connectionsUSERNAME = MDMDBE4 # Username used in the connectionPASSWORD = "ENCRYPT:YEE7cEZs+HE+mEHCsdNOfg==" # Password used in the connection#HOST = # Master hostname used when attempting a connection.PROTOCOL = https # Protocol used to establish a connection with the Master.#PROTOCOL = http # Protocol used to establish a connection with the Master.PORT = 3111 # Protocol port#PROXY =#PROXYPORT =TIMEOUT = 120 # Timeout in seconds to wait a server response#DEFAULTWS =

CLI SSL keystore file = "$(install_dir)/ssl/MyTWSKeyRing.kdb"CLI SSL certificate keystore label = "client"CLI SSL keystore pwd = "$(install_dir)/ssl/MyTWSKeyRing.sth"

The SSL configuration options for the command line client depend on the type ofSSL implemented - here GSKit is assumed.

Note: The # symbol is used to comment a line.

Multiple product instancesBecause Tivoli Workload Scheduler supports multiple product instances installedon the same computer, there can be more than one instance of the useropts file peruser. This is achieved by giving the useropts files for a user different names foreach instance.

In the localopts file of each instance the option named useropts identifies the filename of the useropts file that has to be accessed in the user_home/.TWS directoryto connect to that installation instance.

This means that, for example, if two Tivoli Workload Scheduler instances areinstalled on a computer and the user operator is a user of both instances, youcould define the useropts credentials as follows:


v In the localopts file of the first instance the local option useropts = useropts1identifies the operator_home/.TWS/useropts1 file containing the connectionparameters settings that user operator needs to use to connect to the first TivoliWorkload Scheduler instance.

v In the localopts file of the second Tivoli Workload Scheduler instance the localoption useropts = useropts2 identifies the operator_home/.TWS/useropts2 filecontaining the connection parameters settings that user operator needs to use toconnect to the second Tivoli Workload Scheduler instance.

Configuring the Tivoli Workload Scheduler agentThe configuration settings of the Tivoli Workload Scheduler agent are contained inthe JobManager.ini file (for the path of this file, see.“Where products andcomponents are installed” on page 1). The file is made up of many differentsections. Each section name is enclosed between square brackets and each sectionincludes a sequence of variable = value statements.

You can customize properties for the following:v Log propertiesv Trace propertiesv Native job executorv Java job executorv Resource advisor agentv System scanner

Not all the properties in the JobManager.ini file can be customized. For a list ofthe configurable properties, see the following sections.

Configuring log message properties[JobManager.Logging.cclog]

To configure the logs, edit the [JobManager.Logging.cclog] section in theJobManager.ini file. This procedure requires that you stop and restart the TivoliWorkload Scheduler agent

The section containing the log properties is named:[JobManager.Logging.cclog]

You can change the following properties:

JobManager.loggerhd.fileNameThe name of the file where messages are to be logged.

JobManager.loggerhd.maxFileBytesThe maximum size that the log file can reach. The default is 1024000 bytes.

JobManager.loggerhd.maxFilesThe maximum number of log files that can be stored. The default is 3.

JobManager.loggerhd.fileEncodingBy default, log files for the dynamic agent are coded in UTF-8 format. Ifyou want to produce the log in a different format, add this property andspecify the required codepage.


||||

JobManager.loggerfl.levelThe amount of information to be provided in the logs. The value rangesfrom 4000 to 7000. Smaller numbers correspond to more detailed logs. Thedefault is 3000.

Configuring trace properties [JobManager.Logging.cclog]You have the following options when configuring traces:v Edit the [JobManager.Logging] section in the JobManager.ini file. This procedure

requires that you stop and restart the Tivoli Workload Scheduler agent.v Use one or more of the following command line commands, without stopping

and restarting the Tivoli Workload Scheduler agent:– enableTrace– disableTrace– showTrace– changeTrace

For more information, see “Configuring traces immediately” on page 45.

The section containing the trace properties is named:[JobManager.Logging.cclog]


JobManager.trhd.fileNameThe name of the trace file.

JobManager.trhd.maxFileBytesThe maximum size that the trace file can reach. The default is 1024000bytes.

JobManager.trhd.maxFilesThe maximum number of trace files that can be stored. The default is 3.

JobManager.trfl.levelDetermines the type of trace messages that are logged. Change this valueto trace more or fewer events, as appropriate, or on request from IBMSoftware Support. Valid values are:

DEBUG_MAXMaximum tracing. Every trace message in the code is written tothe trace logs.

INFO All informational, warning, error and critical trace messages arewritten to the trace. The default value.

WARNINGAll warning, error and critical trace messages are written to thetrace.

ERRORAll error and critical trace messages are written to the trace.

CRITICALOnly messages which cause the agent to stop are written to thetrace.

The output trace (JobManager_trace.log) is provided in XML format.


Configuring traces immediately

Trace files are enabled by default for the Tivoli Workload Scheduler agent. You canuse the following commands to configure traces without stopping and restartingthe agent:

enableTraceSets the trace to the maximum level, producing a verbose result.

disableTraceSets the traces to the lowest level.

showTrace [ >trace_file_name.xml]Displays the current trace settings defined in the [JobManager.Logging]section of the JobManager.ini file. You can also redirect the[JobManager.Logging] section to a file to modify it. Save the modified fileand use the changeTrace command to make the changes effectiveimmediately.

changeTrace [trace_file_name.xml]Reads the file containing the modified trace settings and implements thechanges immediately and permanently, without stopping and restarting theTivoli Workload Scheduler agent.

The following is an example of the file created by the showTrace command:<?xml version="1.0" encoding="UTF-8"?><jmgr:updateConfigurationResponse

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:jmgr="http://www.ibm.com/xmlns/prod/scheduling/1.0/JobManager">

<jmgr:Section name="JobManager.Logging.cclog"><jmgr:Property>

<jmgr:Name>JobManager.trfl.level</jmgr:Name><jmgr:Value>1011</jmgr:Value>

</jmgr:Property><jmgr:Property>

<jmgr:Name>JobManager.trhd.maxFileBytes</jmgr:Name><jmgr:Value>1024000</jmgr:Value>

</jmgr:Property><jmgr:Property>

<jmgr:Name>JobManager.trhd.maxFiles</jmgr:Name><jmgr:Value>4</jmgr:Value>

</jmgr:Property></jmgr:updateConfigurationResponse>

where the JobManager properties indicated are as described in “Configuring traceproperties [JobManager.Logging.cclog]” on page 44.

Configuring common launchers properties [Launchers]

In the JobManager.ini file, the section containing the properties common to thedifferent launchers (or executors) is named:[Launchers]


BaseDirThe installation path of the Tivoli Workload Scheduler agent.

SpoolDirThe path to the folder containing the jobstore and outputs. The default is:value of BaseDir/stdlidst/JM


MaxAgeThe number of days that job logs are kept (in path TWA_home/TWS/stdlidst/JM) before being deleted. The default is 2. Possible values rangefrom a minimum of 1 day.

CommandHandlerMinThreadsThe default is 20.

CommandHandlerMaxThreadsThe default is 100.

ExecutorsMinThreadsThe default is 38.

ExecutorsMaxThreadsThe default is 400.

NotifierMinThreadsThe default is 3.

NotifierMaxThreadsThe default is 5.

DirectoryPermissionsThe access rights assigned to the Tivoli Workload Scheduler for z/OSagents for creating directories when running jobs. The default is 0755.Supported values are UNIX-format entries in hexadecimal notation.

FilePermissionsThe access rights assigned to the Tivoli Workload Scheduler for z/OSagents for creating files when running jobs. The default is 0755. Supportedvalues are UNIX-format entries in hexadecimal notation.

Configuring properties of the native job launcher[NativeJobLauncher]

In the JobManager.ini file, the section containing the properties of the native joblauncher is named:[NativeJobLauncher]


AllowRootApplies to UNIX systems only. Specifies if the root user can run jobs on theagent. It can be true or false. The default is true.

CheckExecIf true, before launching the job, the agent checks both the availability andthe execution rights of the binary file. The default is true.

LoadProfileSpecifies if the user profile is to be loaded. It can be true or false. Thedefault is true.

PortMaxThe maximum range of the port numbers used by the task launcher tocommunicate with the Job Manager. The default is 0, meaning that theoperating system assigns the port automatically.

PortMinThe minimum range of the port numbers used by the task launcher to


||||

||||

communicate with the Job Manager. The default is 0, meaning that theoperating system assigns the port automatically.

RequireUserName

When true, requires that you add the user name in the JSDL job definition.

When false, runs with the user name used by job manager, that is:v TWS_user on UNIX and Linux systemsv The local system account on Windows systems

The default is false.

ScriptSuffixThe suffix to be used when creating the script files. It is:

.cmd For Windows

.sh For UNIX

VerboseTracingEnables verbose tracing. It is set to true by default.

Configuring properties of the Java job launcher[JavaJobLauncher]

In the JobManager.ini file, the section containing the properties of the Java joblauncher is named:[JavaJobLauncher]


JVMDirThe path to the virtual machine used to start job types with advancedoptions. You can change the path to another compatible Java virtualmachine.

JVMOptionsThe options to provide to the Java Virtual Machine used to start job typeswith advanced options. Supported keywords for establishing a secureconnection are:v htttps.proxyHostv https.proxyPort

Supported keywords for establishing a non-secure connection are:v Dhttp.proxyHostv Dhttp.proxyPort

For example, to set job types with advanced options, based on the defaultJVM http protocol handler, to the unauthenticated proxy server called withname myproxyserver.mycompany.com, define the following option:JVMOptions = -Dhttp.proxyHost=myproxyserver.mycompany.com-Dhttp.proxyPort=80

Configuring properties of the Resource advisor agent[ResourceAdvisorAgent]

In the JobManager.ini file, the section containing the properties of the Resourceadvisor agent is named:


||||

|

|

|

|

|

|||

||

[ResourceAdvisorAgent]


CPUScannerPeriodSecondsThe time interval that the Resource advisor agent collects resourceinformation about the local CPU. The default value is every 10 seconds.

FullyQualifiedHostnameThe fully qualified host name of the Tivoli Workload Scheduler agent. It isconfigured automatically at installation time and is used to connect withthe Tivoli Workload Scheduler master or dynamic domain manager. Editonly if the host name is changed after installation.

NotifyToResourceAdvisorPeriodSecondsThe time interval that the Resource advisor agent forwards the collectedresource information to the Resource advisor. The default (and maximumvalue) is every 180 seconds.

ResourceAdvisorUrlThe URL of the Tivoli Workload Scheduler master or dynamic domainmanager that is hosting the dynamic agent. This URL is used until theserver replies with the list of its URLs. The value is https://$(tdwb_server):$(tdwb_port)/JobManagerRESTWeb/JobScheduler/resource,where:

$(tdwb_server)is the fully qualified host name of the Tivoli Workload Schedulermaster or dynamic domain manager.

$(tdwb_port)is the port number of the Tivoli Workload Scheduler master ordynamic domain manager.

It is configured automatically at installation time. Edit only if the hostname or the port number are changed after installation, or if you do notuse secure connection (set to http). If you set the port number to zero, theresource advisor agent does not start. The port is set to zero if atinstallation time you specify that you will not be using the Tivoli WorkloadScheduler master or dynamic domain manager.

BackupResourceAdvisorUrlsThe list of URLs returned by the Tivoli Workload Scheduler master ordynamic domain manager. The agent uses this list to connect to the TivoliWorkload Scheduler master or dynamic domain manager.

ScannerPeriodSecondsThe time interval that the Resource advisor agent collects informationabout all the resources in the local system other than CPU resources. Thedefault value is every 120 seconds.

The resource advisor agent, intermittently scans the resources of the machine(computer system, operating system, file systems and networks) and periodicallysends an update of their status to the Tivoli Workload Scheduler master ordynamic domain manager.

The CPU is scanned every CPUScannerPeriodSeconds seconds, while all the otherresources are scanned every ScannerPeriodSeconds seconds. As soon as one of thescans shows a significant change in the status of a resource, the resources are


||||||

|||

|||

||||||

||||

synchronized with the Tivoli Workload Scheduler master or dynamic domainmanager. The following is the policy followed by the agent to tell if a resourceattribute has significantly changed:v A resource is added or deletedv A string attribute changes its valuev A CPU value changes by more than DeltaForCPU

v A file system value changes by more than DeltaForDiskMB megabytesv A Memory value changes by more than DeltaForMemoryMB megabytes

If there are no significant changes, the resources are synchronized with the TivoliWorkload Scheduler master or dynamic domain manager everyNotifyToResourceAdvisorPeriodSeconds seconds.

Configuring properties of the System scanner[SystemScanner]

In the JobManager.ini file, the section containing the properties of the Systemscanner is named:[SystemScanner]


CPUSamplesThe number of samples used to calculate the average CPU usage. Thedefault value is 3.

DeltaForCPUThe change in CPU usage considered to be significant when it becomeshigher than this percentage (for example, DeltaForCPU is 20 if the CPUusage changes from 10 percent to 30 percent). The default value is 20percent.

DeltaForDiskMBThe change in use of all file system resources that is considered significantwhen it becomes higher than this value. The default value is 100 MB.

DeltaForMemoryMBThe change in use of all system memory that is considered significantwhen it becomes higher than this value. The default value is 100 MB.

Configuring the dynamic workload broker server on the master domainmanager and dynamic domain manager

You can perform these configuration tasks after completing the installation of yourmaster domain manager, dynamic domain manager, and dynamic agents, and anytime that you want to change or tune specific parameters in your environment.

The configuration parameters for the dynamic workload broker server are definedby default at installation time. You modify a subset of these parameters using thefiles that are created when you install dynamic workload broker. The followingfiles are created in the path:

TWA_home/TDWB/config


ResourceAdvisorConfig.propertiesContains configuration information about the Resource Advisor. For moreinformation, see “ResourceAdvisorConfig.properties file” on page 52.

JobDispatcherConfig.propertiesContains configuration information about the Job Dispatcher. For moreinformation, see “JobDispatcherConfig.properties file” on page 54.

BrokerWorkstation.propertiesContains configuration information about the broker server.“BrokerWorkstation.properties file” on page 56

CLIConfig.propertiesContains configuration information for the dynamic workload brokercommand line. This file is described in Tivoli Workload Scheduler: SchedulingWorkload Dynamically.

audit.propertiesContains options for configuring the auditing of events. This file isdocumented in the IBM Tivoli Workload Scheduler: Troubleshooting Guide.

You can modify a subset of the parameters in these files to change the followingsettings:v Heartbeat signal from the dynamic agents.v Time interval for job allocation to resourcesv Time interval for notifications on resourcesv Polling time when checking the status of remote engine workstationsv Maximum number of results when allocating jobs to global resourcesv Encryption of any passwords sent in the JSDL definitionsv Time interval for retrying the operation after a Job Dispatcher failurev Time interval for retrying the operation after a client notification failurev Archive settings for job datav Job history settingsv Command line properties (see IBM Tivoli Workload Scheduler: Scheduling Workload

Dynamically)

The editable parameters are listed in the following sections. If you edit anyparameters that are not listed, the product might not work. After modifying thefiles, you must stop and restart the IBM WebSphere server.

Maintaining the dynamic workload broker server on themaster domain manager and dynamic domain manager

Because one dynamic workload broker server is installed with your master domainmanager and dynamic domain manager, and one server with every backupmanager, you have at least two servers present in your Tivoli Workload Schedulernetwork. The server running with the master domain manager is the only oneactive at any time. The servers installed in the backup managers are idle until youswitch managers, and the server in the new manager becomes the active server(see “Starting, stopping, and displaying dynamic workload broker status” on page298 for important information about this scenario). To have a smooth transitionfrom one server to another, when you switch managers, it is important that youkeep the same configuration settings in the ResourceAdvisorConfig.propertiesand JobDispatcherConfig.properties files in all your servers. When you make a


|

|

|

|||||||||||

change in any of these files of your running dynamic workload broker server,remember to apply the same change also in the dynamic workload broker serveridling on your backup manager.

Some of the settings for the dynamic workload broker server are stored in the localBrokerWorkstation.properties file and also in the Tivoli Workload Schedulerdatabase. When you switch to the backup master domain manager or dynamicdomain manager, the dynamic workload broker server settings are automaticallyupdated on the backup workstation. For more information about theBrokerWorkstation.properties file, see “BrokerWorkstation.properties file” on page56.

Note: The database is automatically populated with the information from theactive workstation, regardless of whether it is the manager or the backupworkstation. For example, if you modify the dynamic workload brokerserver settings on the backup master domain manager or dynamic domainmanager, this change is recorded in the database. When you switch back tothe manager workstation, the change is applied to the master domainmanager or dynamic domain manager and the related local settings areoverwritten.

It is important that you also keep the data pertinent to every dynamic workloadbroker server up-to-date. If you change the host name or port number of any ofyour dynamic workload broker servers, use the exportserverdata andimportserverdata commands from the dynamic workload broker command line torecord these changes in the Tivoli Workload Scheduler database. For informationabout these commands, see Scheduling Workload Dynamically.

The database records for your workload broker workstations all haveLOCALHOST as the host name of the workstation. Leave the record as-is. Do notreplace LOCALHOST with the actual host name or IP address of the workstation.LOCALHOST is used intentionally to ensure that the jobs submitted from TivoliWorkload Scheduler are successfully sent to the new local dynamic workloadbroker when you switch the master domain manager or dynamic domain manager.

Enabling unsecure communication with the dynamic workloadbroker server

By default, the dynamic workload broker server uses secure communication. Youmight need to enable unsecure communication, even though this type ofcommunication is not recommended.

To enable unsecure communication with the dynamic workload broker server,perform the following steps on the master domain manager:1. Run the exportserverdata command located in installation_directory/TDWB/bin:

exportserverdata -dbUsr db_instance_admin -dbPwd db_instance_admin_pwd

2. Open the resulting server.properties file in a flat-text editor.3. Copy the following line:

https://hostname:port/JobManagerRESTWeb/JobScheduler

4. Change the copied line by replacing https with http:http://hostname:port/JobManagerRESTWeb/JobScheduler

The file now contains two lines specifying the connection mode, one linespecifying the https mode and one line specifying the http mode.


|||

|||||||

||||||||

||||||

||||||

|

|

|||

||

|

|

|

|

|

|

|

||

5. Save the file.6. Import the new data with the importserverdata command located in

installation_directory/TDWB/bin:importserverdata -dbUsr db_instance_admin -dbPwd db_instance_admin_pwd

For more information about the exportserverdata and importserverdata commands,see Tivoli Workload Scheduler: Scheduling Workload Dynamically.

ResourceAdvisorConfig.properties fileThe parameters in this file affect the following dynamic workload broker serversettings:v Heartbeat signal from the dynamic agentsv Time interval for job allocation to resourcesv Time interval for notifications on resourcesv Polling time when checking the status of remote engine workstationsv Maximum number of results when allocating jobs to global resources

You can modify the following parameters in theResourceAdvisorConfig.properties file:

DatabaseCheckIntervalSpecifies the time interval within which the dynamic workload brokerserver checks the availability of the database. The default value is 180seconds.

ResourceAdvisorURLSpecifies the URL of the Resource Advisor.

RaaHeartBeatIntervalSpecifies the time interval within which the Resource Advisor expects aheartbeat signal from the dynamic agent. The default value is 200 seconds.After the maximum number of retries (specified in theMissedHeartBeatCount parameter) is exceeded, the Resource Advisorreports the related computer as unavailable. In a slow network, you mightwant to set this parameter to a higher value. However, defining a highervalue might delay the updates on the availability status of computersystems. If, instead, you decrease this value together with the valuedefined for the NotifyToResourceAdvisorPeriodSeconds parameter, thismight generate network traffic and increase CPU usage when updatingcached data. The value defined in this parameter must be consistent withthe NotifyToResourceAdvisorPeriodSeconds parameter defined in theJobManager.ini file, which defines the time interval for each dynamicagent to send the heartbeat signal to the Resource Advisor.

MissedHeartBeatCountSpecifies the number of missed heartbeat signals after which the computeris listed as not available. The default value is 2. In a slow network, youmight want to set this parameter to a higher value.

MaxWaitingTimeSpecifies the maximum time interval that a job must wait for a resource tobecome available. If the interval expires before a resource becomesavailable, the job status changes to Resource Allocation Failure. The defaultvalue is 600 seconds. You can override this value for each specific job byusing the Maximum Resource Waiting Time parameter defined in the JobBrokering Definition Console. For more information about the MaximumResource Waiting Time parameter, see the Job Brokering Definition


|

||

|

||

|

|||||||||||||||

Console online help. If you set this parameter to -1, no waiting interval isapplied for the jobs. If you set this parameter to 0, the Resource Advisortries once to find the matching resources and, if it does not find anyresource, the job changes to the ALLOCATION FAILED status. If youincrease this value, all submitted jobs remain in WAITING status for alonger time and the Resource Advisor tries to find matching resourcesaccording to the value defined for the CheckInterval parameter.

CheckIntervalSpecifies how long the Resource Advisor waits before retrying to findmatching resources for a job that did not find any resource in the previoustime slot. The default value is 60 seconds.

TimeSlotLengthSpecifies the time slot interval during which the Resource Advisorallocates resources to each job. Jobs submitted after this interval hasexpired are considered in a new time slot. The default value is 15 seconds.The default value is adequate for most environments and should not bemodified. Setting this parameter to a higher value, causes the ResourceAdvisor to assign resources to higher priority jobs rather than to lowerpriority jobs when all jobs are trying to obtain the same resource. It mightalso, however, cause the job resource matching processing to take longerand the resource state updates from agents to be slowed down. Setting thisparameter to a lower value, causes the Resource Advisor to process theresource matching faster and, if you have a high number of agents withfrequent updates, to update the resource repository immediately. If jobrequirements match many resources, lower values ensure a better loadbalancing. If most jobs use resource allocation, do not lower this valuebecause the allocation evaluation requires many processing resources.

NotifyTimeIntervalSpecifies the interval within which the Resource Advisor retries to sendnotifications on the job status to the Job Dispatcher after a notificationfailed. The default value is 15 seconds. The default value is adequate formost environments and should not be modified.

MaxNotificationCountSpecifies the maximum number of attempts for the Resource Advisor tosend notifications to the Job Dispatcher. The default value is 100. Thedefault value is adequate for most environments and should not bemodified.

ServersCacheRefreshInterval

Specifies with what frequency (in seconds) the Resource Advisor checksthe list of active and backup workload broker servers for updates. This listis initially created when the master domain manager is installed, and afterthat it is updated every time a new backup master is installed andconnected to the master domain manager database (the master domainmanager and every backup master include also a workload broker server).When the Resource Advisor agents send their data about the resourcesdiscovered in each computer, they are able to automatically switch betweenthe servers of this list, so that the workload broker server that is currentlyactive can store this data in its Resource Repository. For this reason, theResource Advisor agents must know at all times the list of all workloadbroker servers. The possible values range between 300 (5 minutes) and43200 (12 hours). The default value is 3600 seconds.


StatusCheckIntervalSpecifies the time interval in seconds the Resource Advisor waits beforepolling for the status of a resource. For example this timeout applies whenchecking the status of a remote engine. The default value is 120 seconds.

After modifying the file, you must stop and restart the WebSphere ApplicationServer.

JobDispatcherConfig.properties fileThe parameters in this file affect the following dynamic workload broker serversettings:v Encryption of any passwords sent in the JSDL definitionsv Time interval for retrying the operation after a Job Dispatcher failurev Time interval for retrying the operation after a client notification failurev Archive settings for job datav Job history settings

In the JobDispatcherConfig.properties file, the following parameters areavailable:

DatabaseCheckIntervalSpecifies the time interval within which the dynamic workload brokerserver checks the availability of the database. The default value is 180seconds.

EnablePasswordEncryptionSpecifies that any user passwords contained in the JSDL definitions are tobe encrypted when the definitions are sent to the dynamic agents. Thedefault is true. Setting this property to false forces the workload brokerserver to send the passwords in plain text. This applies to any passwordfield.

RAEndpointAddressSpecifies the URL of the Resource Advisor.

JDURLSpecifies the URL of the Job Dispatcher.

FailQIntervalSpecifies the numbers of seconds for retrying the operation after thefollowing failures:v Client notification.v Allocation, Reallocate, Cancel Allocation requests to Resource Advisor.v Any database operation failed for connectivity reasons.

The default value is 30 seconds. Increasing this value improves recoveryspeed after a failure but can use many system resources if the recoveryoperation is complex. For example, if the workload broker workstation isprocessing a new Symphony file, this operation might require some time,so you should set this parameter to a high value. If you are not usingworkload broker workstation, this parameter can be set to a lower value.

MaxCancelJobAttemptsCountThe maximum number of times the Job Dispatcher attempts to cancel ashadow job or a job running on a dynamic agent when a request to kill thejob is made and the kill request cannot be immediately processed. The


||||

||||

default is 1440 attempts. The Job Dispatcher attempts to cancel the jobevery 30 seconds for a maximum number of times specified by thisparameter.

MaxNotificationCountSpecifies the maximum number of retries after a client notification failure.The default value is 1440. For example, if the workload broker workstationis processing a new Symphony file, this operation might require sometime, so you should set this parameter to a high value. If you are not usingthe workload broker workstation, this parameter can be set to a lowervalue.

MoveHistoryDataFrequencyInMinsSpecifies how often job data must be moved to the archive tables in theJob Repository database and the tables in the archive database must bedropped. The unit of measurement is minutes. The default value is 60minutes. Increasing this value causes the Job Dispatcher to check lessfrequently for jobs to be moved. Therefore, the volume of jobs in the JobRepository might increase and all queries might take longer to complete.Dynamic workload broker servers with high job throughput might requirelower values, while low job throughputs might require higher values.

SuccessfulJobsMaxAgeSpecifies how long successfully completed or canceled jobs must be kept inthe Job Repository database before being archived. The unit ofmeasurement is hours. The default value is 240 hours, that is ten days.

UnsuccessfulJobsMaxAgeSpecifies how long unsuccessfully completed jobs or jobs in unknownstatus must be kept in the Job Repository database before being archived.The unit of measurement is hours. The default value is 720 hours, that is30 days.

ArchivedJobsMaxAgeSpecifies how long jobs must be kept in the archive database before beingdeleted. The unit of measurement is hours. The default value is 720 hours,that is 30 days.

AgentConnectTimeoutSpecifies the number of minutes that the workload broker server waits fora scheduling agent response after it first attempts to establish a connectionwith that agent. If the agent does not reply within this time, the serverdoes not open the connection. Values range from 0 to 60 (use 0 to waitindefinitely). The default is 3.

AgentReadTimeoutSpecifies the number of minutes that the workload broker server waits toreceive data from established connections with a scheduling agent. If nodata arrives within the specified time, the server closes the connection withthe agent. Values range from 0 to 60 (use 0 to wait indefinitely). Thedefault is 3.

You can use this file to configure the product behavior when archiving job data.For more information about archive tables, see “Historical database tables createdduring installation” on page 57.

If an unexpected job workload peak occurs and a cleanup of the database isrequired earlier than the value you specified in the


|||

||||

|||||

||||

MoveHistoryDataFrequencyInMins parameter, you can use the movehistorydatacommand to perform a cleanup before the scheduled cleanup is performed.

After modifying the file, you must stop and restart the IBM WebSphere server.

BrokerWorkstation.properties fileIf you need to make configuration changes to the broker server after theinstallation has completed, you can edit the BrokerWorkstation.properties file.The BrokerWorkstation.properties file contains the following configurationproperties:

DomainManager.Workstation.NameThe name of the domain manager workstation.

DomainManager.Workstation.PortThe port of the domain manager workstation.

MasterDomainManager.NameThe name of the master domain manager workstation.

Broker.Workstation.NameThe name of the broker server in the Tivoli Workload Scheduler productionplan. This name is first assigned at installation time.

MasterDomainManager.HostNameThe host name of the master domain manager workstation.

MasterDomainManager.HttpsPortThe HTTPS port of the master domain manager workstation.

Broker.Workstation.PortThe port used by the broker server to listen to the incoming traffic(equivalent to the Netman port). It is first assigned at installation time.This port number must always be the same for all the broker servers thatyou define in your Tivoli Workload Scheduler network (one with themaster domain manager and one with every backup master you install) toensure consistency when you switch masters.

DomainManager.Workstation.DomainThe name of the domain where the broker server is registered.

Broker.AuthorizedCNsThe list of prefixes of common names authorized to communicate with thebroker server. For more information about authorizing the connection tothe dynamic domain manager, see “Customizing the SSL connection to themaster domain manager and dynamic domain manager” on page 197.

Broker.Workstation.EnableA switch that enables or disables the broker server. The value can be trueor false. The default value is true.

Set this value to false if you decide not to use a broker server. Not usingthe broker server means that you can submit jobs dynamically on theworkload broker directly (using either the Dynamic Workload Console orthe workload broker command line) without using the scheduling facilitiesof Tivoli Workload Scheduler.

Broker.Workstation.CpuTypeThe workstation type assigned to the broker server. Supported values are:v master domain manager (master)v backup master domain manager (fta)


|

||||

||

||

||

|||

||

||

|||||||

||

|||||

|||

|||||

||

|

|

v dynamic domain manager (fta, broker, agent)v backup dynamic domain manager (fta, broker, agent)

Broker.Workstation.RetryLinkThe number of seconds between consecutive attempts to link to the brokerserver. The default is 600.

Note that no SSL security is available for the connection between the masterdomain manager and the broker server. All the data between the two workstationsis sent unencrypted. If this might cause a security risk in your environment, youcan choose not to use the broker server functions, by settingBroker.Workstation.Enable to false.

Archiving job dataJob definitions created using the Job Brokering Definition Console or the DynamicWorkload Console are stored in the Job Repository database. The Job Repositorydatabase stores also the jobs created when the job definitions are submitted to thedynamic workload broker.

Job information is archived on a regular basis. By default, successful jobs arearchived every 24 hours. Jobs in failed or unknown status are archived by defaultevery 72 hours. Archived jobs are moved to historical tables in the Job Repository.

You can configure the time interval after which job data is archived using thefollowing parameters:v MoveHistoryDataFrequencyInMins

v SuccessfulJobsMaxAge

v UnsuccessfulJobsMaxAge

v ArchivedJobsMaxAge

These parameters are available in the JobDispatcherConfig.properties file, asdescribed in “JobDispatcherConfig.properties file” on page 54. You can also use themovehistorydata command to perform a cleanup before the scheduled cleanup isperformed.

Historical database tables created during installation

Database creation differs depending on the database vendor you are using. If youare using DB2®, two databases are created by default when the dynamic workloadbroker server is installed. If you are using Oracle, two schemas are created in thesame database. The names for both the databases and the schemas are as follows:

IBMCDB (DB2 )/ CDB (Oracle)Contains Agent manager data. The name is fixed and cannot be changed.

TDWBContains dynamic workload broker data. You can change the name.

The following three historical tables are created during the installation process inthe TDWB database. These tables are used to contain historical data about jobinstances.

JOA_JOB_ARCHIVESContains archived job instances. See Table 13 on page 58.

JRA_JOB_RESOURCE_ARCHIVESContains resource information related to a job. See Table 14 on page 58.


|

|

|||

|||||

MEA_METRIC_ARCHIVESContains metrics collected for a job. See Table 15 on page 59.

To improve RDBMS performance, you can move data from the standard tables tohistorical tables on a regular basis. You can configure RDBMS maintenance usingthe JobDispatcherConfig.properties file. For more information, see“JobDispatcherConfig.properties file” on page 54. You can also use themovehistorydata command to move data to the historical tables and deletearchived data.

Table 13. JOA_JOB_ARCHIVES database table

Column Name DB2 Data TypeOracle DataType Length Nullable Description

JOA_ID CHAR () FORBIT DATA

RAW 16 No Contains the unique identifier ofthe job

JOA_START_TIME TIMESTAMP TIMESTAMP 26 Yes The start time of the job, ifstarted

JOA_END_TIME TIMESTAMP TIMESTAMP 26 Yes The end time of the job, if ended

JOA_JSDL_INSTANCE CLOB CLOB No The JSDL (job definition), storedin binary format

JOA_SUBMIT_USERNAME VARCHAR VARCHAR2 120 No The submitter

JOA_TIMEZONE VARCHAR VARCHAR2 40 Yes Not used in this release

JOA_STATE DECIMAL NUMBER 2 No The job state code

JOA_RETURN_CODE DECIMAL NUMBER 10 No The job return code

JOA_SUBMIT_TIME TIMESTAMP TIMESTAMP 26 No The submit time

JOA_NAME VARCHAR VARCHAR2 250 No The job definition name

JOA_NAMESPACE VARCHAR VARCHAR2 250 Yes The job definition namespace

JOA_ALIAS_NAME VARCHAR VARCHAR2 250 Yes The job definition alias

JOA_SUBMITTER_TYPE VARCHAR VARCHAR2 80 Yes The submitter type (for example,TDWB CLI, TDWB UI)

JOA_UPDATE_TIME TIMESTAMP TIMESTAMP 26 No The last update timestamp ofactual row

Table 14. JRA_JOB_RESOURCE_ARCHIVES database table

Column Name DB2 Data TypeOracle Datatype Length Nullable Description

JOA_ID CHAR () FOR BITDATA

RAW 16 No Contains the uniqueidentifier of the job

JRA_RESOURCE_NAME VARCHAR VARCHAR2 250 No The resource internal name

JRA_RESOURCE_TYPE VARCHAR VARCHAR2 30 No The resource type (forexample, ComputerSystem,FileSystem, ...)

JRA_RESOURCE_GROUP DECIMAL NUMBER 5 No The group code (grouping anallocation for actual job)

JRA_DISPLAY_NAME VARCHAR VARCHAR2 250 Yes The displayed name

JRA_IS_TARGET DECIMAL NUMBER 1 No A flag indicating the rootresource (typically theComputerSystem)


Table 15. MEA_METRIC_ARCHIVES database table

Column Name DB2 Data TypeOracle DataType Length Nullable Description

JOA_ID CHAR () FOR BITDATA

RAW 16 No Contains the unique identifier ofthe job

MEA_NAME VARCHAR VARCHAR2 80 No The metric name (for example,JOB_MEMORY_USAGE,JOB_CPU_USAGE, ...)

MEA_TYPE CHAR CHARACTER 10 No The metric datatype (for example,DECIMAL, ...)

MEA_VALUE VARCHAR VARCHAR2 250 No The metric value

Table 16 lists the status of jobs as stored in the historical tables in association withthe job status available in the Tivoli Dynamic Workload Console and in thecommand line, mapping them with the related options in the movehistorydatacommand.

Table 16. Job statuses in the historical tables

movehistorydata option Job statusin tables

Tivoli Dynamic WorkloadConsole status

Command line status

SuccessfulJobsMaxAge 43 Completed successfully SUCCEEDED_EXECUTION

44 Canceled CANCELED

UnsuccessfulJobMaxAge 41 Resource allocation failed RESOURCE_ ALLOCATION_FAILED

42 Run failed FAILED_EXECUTION

45 Unknown UNKNOWN

46 Unable to start NOT_EXECUTED

Configuring to schedule J2EE jobs

Using the dynamic workload broker component you can schedule J2EE jobs. To dothis you must complete the following configuration tasks:v Configure the J2EE executor on every agent on which you submit J2EE jobs.v Configure the J2EE Job Executor Agent on an external WebSphere Application

Server

Configuring the J2EE executor

To dynamically schedule J2EE jobs, you must configure the following property fileson every agent on which you submit J2EE jobs:v J2EEJobExecutorConfig.propertiesv logging.propertiesv soap.client.props

These files are configured with default values at installation time. The values thatyou can customize are indicated within the description of each file.

J2EEJobExecutorConfig.properties file: The path to this file isTWA_home/TWS/JavaExt/cfg/J2EEJobExecutorConfig.properties(TWA_home\TWS\JavaExt\cfg\J2EEJobExecutorConfig.properties) on the agent.


The keywords of this file are described in the following table:

Table 17. J2EEJobExecutorConfig.properties file keywords

Keyword Specifies... Default value Must be customized

wasjaas.default The path to the IBMWebSphere configuration file(wsjaas_client.conf) usedto authenticate on theexternal WebSphereApplication Server usingJAAS security.

TWA_home/TWS/JavaExt/cfg/wsjaas_client.conf orTWA_home\TWS\JavaExt\cfg\wsjaas_client.conf

Optionally yes, if youmove the file to the pathyou specify.

credentials.mycred The credentials (ID andpassword) used to establishthe SOAP connection to theexternal WebSphereApplication Serverwhenusing indirect scheduling(the password must be {xor}encrypted)

wasadmin,{xor}KD4sPjsyNjE\=

(ID=wasadmin andpassword=wasadmin in {xor}encrypted format)

Yes, see “Running {xor}encryption on yourpassword” on page 61 tolearn how to encrypt yourpassword.

connector.indirect The name of thecommunication channel withWebSphere ApplicationServer. Selecting an indirectinvoker means that dynamicworkload broker uses anexisting WebSphereApplication Serverscheduling infrastructurethat is already configured ona target external WebSphereApplication Server. Whencreating the job definition,you can specify if you wantto use a direct or indirectconnector in the J2EEApplication pane in theApplication page in the JobBrokering DefinitionConsole, or in the invokerelement in the JSDL file. Formore information about theJob Brokering DefinitionConsole, see the online help.

A single line with the followingvalues separated by commas:

v indirect keyword

v Name of the scheduler:

sch/MyScheduler

v soap keyword

v Host name of the externalWebSphere Application Serverinstance:

washost.mydomain.com

v SOAP port of the WebSphereApplication Server instance:

8880

v Path to the soap.client.propsfile:

TWA_home/TWS/JavaExt/cfg/soap.client.props

v Credentials keyword:

mycred

You must customize thefollowing:

v The scheduler name.Replace thesch/MyScheduler stringwith the JNDI name ofthe IBM WebSpherescheduler that you planto use.

v The host name of theexternal WebSphereApplication Serverinstance.

v The SOAP port of theexternal WebSphereApplication Serverinstance.


Table 17. J2EEJobExecutorConfig.properties file keywords (continued)

Keyword Specifies... Default value Must be customized

connector.direct The name of the directcommunication channelwithout using theWebSphere ApplicationServer scheduler. Select adirect invoker to havedynamic workloadbrokerimmediately forwardthe job to the externalWebSphere ApplicationServer instance components(EJB or JMS). When creatingthe job definition, you canspecify if you want to use adirect or indirect connectorin the J2EE Applicationpane in the Applicationpage in the Job BrokeringDefinition Console, or in theinvoker element in the JSDLfile. For more informationabout the Job BrokeringDefinition Console, see theonline help.

A single line with the followingvalues separated by commas:

v direct keyword

v The following string:

com.ibm.websphere.naming.WsnInitialContextFactory

v The following string:

corbaloc:iiop:washost.mydomain.com:2809

You must customize thefollowing:

v The host name of theexternal WebSphereApplication Serverinstance:washost.mydomain.com

v The RMI port of theexternal WebSphereApplication Serverinstance: 2809

trustStore.path The path to the WebSphereApplication Server trustStorefile (this file must be copiedto this local path from theWebSphere ApplicationServer instance).

TWA_home/TWS/JavaExt/cfg/DummyClientTrustFile.jks

You can change the path(TWA_home/TWS/JavaExt/cfg), if you copythe trustStore path fromthe external WebSphereApplication Server to thispath.

trustStore.password The password for theWebSphere ApplicationServer trustStore file.

WebAs Yes

Running {xor} encryption on your password:

To {xor} encrypt your password, use the PropFilePasswordEncoder commandlocated in the WAS_home/bin directory of the external WebSphere ApplicationServer.

Follow these steps:1. Open a new text file and write the following line:

string=your_password_in_plain_text

2. Save the file with a file_name of your choice.3. Run PropFilePasswordEncoder as follows:

PropFilePasswordEncoder file_name string

where:

file_nameIs the name of the file with your password.


string Is the string you used in the text file. This can be any word that youchoose, for example, password, mypwd, joe, and so on.

4. When the command completes, open the text file again. The content haschanged to:string={xor}your_encrypted_password

5. Copy your encrypted password, inclusive of the {xor} characters, and paste itwhere required into your property files.

For example, if you want to encrypt your password catamaran. Proceed as follows:1. Open a text file and write the following:

mypasswd=catamaran

2. Save the file with name encrfile.txt.3. Run:

PropFilePasswordEncoder encrfile.txt mypasswd

4. Open encrfile.txt. You find:mypasswd={xor}PD4rPjI+LT4x

5. Copy {xor}PD4rPjI+LT4x and paste it where you need to.

The logging.properties file:

The path to this file is TWA_home/TWS/JavaExt/cfg/logging.properties(TWA_home\TWS\JavaExt\cfg\logging.properties) on the agent.

After installation, this file is as follows:# Specify the handlers to create in the root logger# (all loggers are children of the root logger)# The following creates two handlershandlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

# Set the default logging level for the root logger.level = INFO

# Set the default logging level for new ConsoleHandler instancesjava.util.logging.ConsoleHandler.level = INFO

# Set the default logging level for new FileHandler instancesjava.util.logging.FileHandler.level = ALLjava.util.logging.FileHandler.pattern =C:\TWA_home\TWS\JavaExt\logs\javaExecutor%g.log

java.util.logging.FileHandler.limit = 1000000java.util.logging.FileHandler.count = 10

# Set the default formatter for new ConsoleHandler instancesjava.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatterjava.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

# Set the default logging level for the logger named com.mycompanycom.ibm.scheduling = INFO

You can customize:v The logging level (from INFO to WARNING, ERROR, or ALL) in the following

keywords:

.level Defines the logging level for the internal logger.


||

||

com.ibm.schedulingDefines the logging level for the job types with advanced options. To loginformation about job types with advanced options, set this keyword toALL.

v The path where the logs are written, specified by the following keyword:java.util.logging.FileHandler.pattern

The soap.client.props file:

The path to this file is TWA_home/TWS/JavaExt/cfg/soap.client.props(TWA_home\TWS\JavaExt\cfg\soap.client.props) on the agent.

After installation, this file is as follows:#------------------------------------------------------------------------------# SOAP Client Security Enablement## - security enabled status ( false[default], true )#------------------------------------------------------------------------------com.ibm.SOAP.securityEnabled=false

com.ibm.SOAP.loginUserid=wasadmincom.ibm.SOAP.loginPassword={xor}KD4sPjsyNjE\=

#------------------------------------------------------------------------------# SOAP Login Prompt## The auto prompting will happen only if all of the following are met:## - Running from a SOAP client# - Server is reachable and server security is enabled# - Username and password are not provided either on command line or in this# file# - com.ibm.SOAP.loginSource below is set to either "stdin" or "prompt"## stdin: prompt in command window# prompt: GUI dialog box; falls back to stdin if GUI not allowed## (So to disable auto prompting, set loginSource to nothing)#------------------------------------------------------------------------------com.ibm.SOAP.loginSource=prompt

#------------------------------------------------------------------------------# SOAP Request Timeout## - timeout (specified in seconds [default 180], 0 implies no timeout)##------------------------------------------------------------------------------com.ibm.SOAP.requestTimeout=180

#------------------------------------------------------------------------------# SSL configuration alias referenced in ssl.client.props#------------------------------------------------------------------------------com.ibm.ssl.alias=DefaultSSLSettings

If you want to enable SOAP client security, you must:1. Change com.ibm.SOAP.securityEnabled to true

2. Customize:v com.ibm.SOAP.loginUserid with the true WebSphere Application Server

administrator user ID.


||||

v com.ibm.SOAP.loginPassword with the true WebSphere Application Serveradministrator password in {xor} encrypted format. See “Running {xor}encryption on your password” on page 61.

Configuring the J2EE Job Executor Agent

To set up the environment on the external WebSphere Application Server, Version7.0 for the J2EE Job Executor Agent, do the following:

Create a Service Integration Bus

1. Open the WebSphere Administrative Console (for example,http://localhost:9060/admin, depending on the admin port you configured).

2. Expand Service Integration and select Buses. The Buses window is displayed.3. Click New to display the Buses configuration window.4. Type a name for the new bus, for example MyBus and click Next and then

Finish to confirm.5. Click the MyBus name and the MyBus properties are displayed.6. Under Topology, click Bus Members. The Buses→MyBus→Bus members

window is displayed.7. Click Add, select the Server radio button, choose

<your_application_server_name>, click Next, and then click Finish.8. When the Confirm the addition of a new bus member panel is displayed,

click Finish.9. Select Service Integration → Buses → MyBus → Destinations → New.

10. Select Queue as the type and click Next

11. Type BusQueue as the identifier and assign the queue to a bus member. ClickNext. In the confirmation panel click Finish.

Configure the Default Messaging Service

1. From the left panel of the WebSphere Administrative Console, expandResources→ JMS→ JMS Providers, then click Default messaging at the serverlevel as scope.

2. In the Connection Factories section, click New.3. On the New JMS connection factory window, fill in the following fields:

Name MyCF

JNDI namejms/MyCF

Bus nameMyBus

Provider endpoints<hostname>:<Basic SIB portnumber>:BootstrapBasicMessaging;<hostname>:<Secure SIB portnumber>:BootstrapSecureMessaging,

where, <Basic SIB port number> and <Secure SIB port number> can befound by expanding Servers, selecting<your_application_server_name>, and then selecting Messagingengine inbound transports under Server Messaging.

4. Select again Resources -→ JMS-→ JMS Providers → Default Messaging at theserver level as scope, locate the section Destinations, and click Queues. ClickNew and fill in the following fields as shown:


||

Name=MyQueueJNDI name=jms/MyQueueBus name=MyBusQueue name=BusQueue

Click Ok.5. Select again Resources → JMS → JMS Providers → Default Messaging at the

server level as scope, and locate the section Activation Specifications.6. Click JMS activation specification. Click New and fill in the following fields as

shown:Name=MyActSpecJNDI name=eis/MyActSpecBus name=MyBusDestination type=QueueDestination JNDI name=jms/MyQueue

Click Ok.

Configure the Java security

1. Select Security → Secure Administration, applications and infrastructure.2. Locate the Authentication section, expand the Java Authentication and

Authorization Service, and click J2C authentication data.3. Click New and fill in the following fields as shown:

Alias=usrUser ID=usrPassword=pwd

where usr is the user ID authenticated when using connector security and pwdis the related password.

4. Click Ok.

Create an XA DataSource

1. In the left pane, go to Resources → JDBC..→ JDBCProviders. In the resultingright pane, check that the scope is pointing to<your_application_server_name>.

2. Locate the DERBY JDBC Provider (XA) entry and click it.3. Locate the Additional Properties section and click Data Sources.4. Click New and fill in the following fields as shown:

Name = MyScheduler XA DataSourceJNDI name = jdbc/SchedulerXADSDatabase name = ${USER_INSTALL_ROOT}/databases/Schedulers/${SERVER}/SchedulerDB;create=true

5. At the top of the page, click Test connection button.6. Even if you get a negative result, modify the Database name field, deleting the

part ;create=true. Click Ok.

Create a WorkManager

1. In the left pane, go to Resources → Asynchronous beans → Work managers andclick New.

2. Fill in the following fields as shown:Name=SchedulerWMJNDI name=wm/SchedulerWM

3. Click Ok.


Create and configure a scheduler

1. In the left pane, go to Resources → Schedulers and click New.2. Fill in the following fields as shown:

Name=MySchedulerJNDI name=sch/MySchedulerData source JNDI name=jdbc/SchedulerXADSTable prefix=MYSCHEDWork managers JNDI name=wm/SchedulerWM

3. Click Ok.4. Select MyScheduler and click Create tables.5. Deploy the test application.

Security order of precedence used for running J2EE tasksThere are three ways of verifying that a task runs with the correct user credentials.Tasks run with specified security credentials using the following methods:1. Java Authentication and Authorization Service (JAAS) security context on the

thread when the task was created.2. setAuthenticationAlias method on the TaskInfo object.3. A specified security identity on a BeanTaskInfo task TaskHandler EJB method.

The authentication methods are performed in the order listed above, so that if anauthentication method succeeds, the following checks are ignored. This means thatthe usr and pwd credentials defined in Configure the Java security take precedenceover any credentials specified in the tasks themselves.

Configuring to schedule job types with advanced options

In addition to defining job types with advanced options using the DynamicWorkload Console or the composer command, you can use the relatedconfiguration files. The options you define in the configuration files apply to all jobtypes with advanced options of the same type. You can override these optionswhen defining the job using the Dynamic Workload Console or the composercommand.

Configuration files are available on each dynamic agent in TWA_home/TWS/JavaExt/cfg for the following job types with advanced options:

Table 18. Configuration files for job types with advanced options

Job type File name Keyword

v Database job type

v MSSQL Job

DatabaseJobExecutor.properties Use the jdbcDriversPath keyword to specifythe path to the JDBC drivers. Define thekeyword so that it points to the JDBC jar filesdirectory, for example:

jdbcDriversPath=c:\\mydir\\jars\\jdbc

The JDBC jar files must be located in thespecified directory or its subdirectories.Ensure you have list permissions on thedirectory and its sub subdirectories.Note: For the MSSQL database, use version 4of the JDBC drivers.


|

||||||

||

||

|||

|

|

|||||

|

||||||

Table 18. Configuration files for job types with advanced options (continued)

Job type File name Keyword

Java job type JavaJobExecutor.properties Use the jarPath keyword to specify the pathto the directory where the jar files are stored.This includes all jar files stored in thespecified directory and all sub directories.

J2EE job type J2EEJobExecutorConfig.properties For more information about the J2EE job type,see “Configuring to schedule J2EE jobs” onpage 59.

Configuring security roles for users and groupsAt Dynamic Workload Console installation time, new predefined roles and groupsare created in Tivoli Integrated Portal. These roles determine which DynamicWorkload Console windows are available to a user, and therefore which activitiesthe user is authorized to perform from the Dynamic Workload Console. If you donot assign a role to a Tivoli Integrated Portal user, that user does not see any entryfor workload broker in the navigation tree. Access to the entries in the navigationtree does not mean that the user can access product functions. There is a secondlevel of authorization, which is determined by a set of security roles created atmaster domain manager installation time in WebSphere Application Server. Theseroles define the levels of authorization needed to perform product functionsregardless of the interface used.

You must therefore map the users and roles in WebSphere Application Server tomatch the users and roles defined in the Tivoli Integrated Portal so thatcommunication between the Dynamic Workload Console and the workload brokerinstance is ensured. This procedure is described in “Mapping security roles tousers and groups in WebSphere Application Server”

Mapping security roles to users and groups in WebSphereApplication Server

When the workload broker instance is installed on your master domain manager,corresponding roles are set up in WebSphere Application Server. By default, theseroles are not used. However, if you enable global security in your environment, theauthorization required to perform any tasks is always validated by WebSphereApplication Server. Users are required to provide credentials for accessing dynamicscheduling tasks. These credentials correspond to existing users defined in thedomain user registry or the LDAP server.

To allow users and groups to access the workload broker functions when globalsecurity is enabled, they must be mapped to the security roles in WebSphereApplication Server. This mapping allows those users and groups to accessapplications defined by the role. At installation time, the following actor roles arecreated in the WebSphere Application Server:

OperatorMonitors and controls the jobs submitted.

AdministratorManages the scheduling infrastructure.

DeveloperDefines the jobs to be run specifying the job parameters, resourcerequirements, and so on.


|

|||

||||||

||||||

|

SubmitterManages the submission of their own jobs and monitors and controls thejob lifecycle. This is the typical role for a Tivoli Workload Scheduler user.

Tivoli Workload Scheduler acts as submitter of jobs to the Tivoli WorkloadScheduler dynamic agent.

ConfiguratorIs the entity responsible for running the jobs on a local environment.

To map security roles to users and groups on the WebSphere Application Serveryou must modify the BrokerSecurityProps.properties file using thechangeBrokerSecurityProperties script.

To avoid the risk of changing a configuration value inadvertently or of overwritingthe latest changes, you should always first create a file containing the currentproperties, edit it to the values you require, and apply the changes. Proceed asfollows:1. Log on to the computer where Tivoli Workload Scheduler is installed as the

following user:

UNIX root

WindowsAny user in the Administrators group.

2. Access the directory: <TWA_home>/wastools3. Stop the WebSphere Application Server using the conman stopappserver

command (see “Starting and stopping the application server andappservman” on page 303)

4. From that same directory run the following script to create a file containingthe current broker security properties:

UNIX showBrokerSecurityProperties.sh > my_file_name

WindowsshowBrokerSecurityProperties.bat > my_file_name

5. Edit my_file_name with a text editor.6. Edit the properties as you require. For each of the roles in the file, you can set

the following properties:

Everyone?Possible values:v Yes: Every user is authorized to perform tasks for the role. No

check is performed on the WebSphere Application Server userregistry.

v No : Access is denied to users not defined in the WebSphereApplication Server user registry.

All authenticated?Possible values:v Yes: All users belonging to the current WebSphere Application

Server user registry who have been authenticated can accessresources and tasks for the role. This is the default value.

v No : Access is granted only to those users and groups defined inthe WebSphere Application Server user registry and listed in themapped user and mapped group properties.


Mapped usersIf specified, one or more users separated by the vertical bar symbol(|). This field can be left blank.

Mapped groupsIf specified, one or more groups separated by the vertical bar symbol(|). This field can be left blank.

7. Save the file my_file_name.8. Run the script:

WindowschangeBrokerSecurityProperties.bat my_file_name

UNIX changeBrokerSecurityProperties.sh my_file_name

where my_file_name is the fully qualified path of the file containing the newparameters.The properties are updated, according to the rules given in the descriptions ofeach property type.

9. Start the WebSphere Application Server using the conman startappservercommand (see “Starting and stopping the application server andappservman” on page 303)

10. Check that the change has been implemented.

Note:

1. If the mapped user or group names contain blanks, the entire user orgroup list must be specified between double quotes ("). For example, ifyou want to add the users John Smith, MaryWhite and DavidC to thedeveloper role, you specify them as follows:Role: DeveloperEveryone?: NoAll authenticated?: NoMapped users:"John Smith|MaryWhite|DavidC"Mapped groups:

2. In the file there is an additional default role named WSClient which youmust leave as is.

Examples: To assign the Operator role to users Susanna and Ann belonging to thecurrent WebSphere Application Server user registry:Role: OperatorEveryone?: NoAll authenticated?: NoMapped users:Susanna|AnnMapped groups:

To assign the Administrator role to user Tom and the Developer role to the usergroup MyGroup defined in the current WebSphere Application Server userregistry:Role: AdministratorEveryone?: NoAll authenticated?: NoMapped users:TomMapped groups:

Role: Developer


Everyone?: NoAll authenticated?: NoMapped users:Mapped groups:MyGroup

BrokerSecurityProps.properties file################################################################# Broker Security Properties################################################################

Role: WSClientEveryone?: NoAll authenticated?: YesMapped users:Mapped groups:

Role: AdministratorEveryone?: NoAll authenticated?: YesMapped users:Mapped groups:

Role: OperatorEveryone?: NoAll authenticated?: YesMapped users:Mapped groups:

Role: SubmitterEveryone?: NoAll authenticated?: YesMapped users:Mapped groups:

Role: ConfiguratorEveryone?: NoAll authenticated?: YesMapped users:Mapped groups:

Role: DeveloperEveryone?: NoAll authenticated?: YesMapped users:Mapped groups:

Configuring command-line client access authenticationThis section describes how to reconfigure the connection used by the commandline client.

The command line client is installed automatically on the master domain managerand can be installed optionally on any other workstation. On the master domainmanager you use it to run all of the commands and utilities.

On any other workstation you use it to run one of the following commands:v evtdef

v composer

v conman (selected subcommands)v optman

v planman


v sendevent

v Selected reports

It is configured automatically by the installation wizard, but if you need to changethe credentials that give access to the server on the master domain manager, oryou want to use it to access a different master domain manager, modify theconnection parameters as described here.

Note:

1. The connection parameters are not required to use the local conmanprogram on a fault-tolerant agent.

2. The command-line client on the master domain manager uses exactly thesame mechanism to communicate with the server as it does when it isinstalled remotely.

Connection parameters

The connection parameters can be provided in one of three ways:

Define them in localoptsAll fields except username and password, can be defined by editing theTWA_home/TWS/localopts properties file on the computer from which theaccess is required. See “Setting local options” on page 23 for a fulldescription of the file and the properties.

In localopts there is a section for the general connection properties, whichcontains the following:host = host_nameprotocol = protocolport = port numberproxy = proxy serverproxyport = proxy server port numbertimeout = secondsdefaultws = master_workstationuseropts = useropts_file

In addition, there are separate groups of SSL parameters which differdepending on whether your network is FIPS-compliant, and thus usesGSKit for SSL, or is not, and uses OpenSSL (see “FIPS compliance” onpage 201 for more details):

FIPS-compliant (GSKit)CLI SSL keystore file = keystore_file_nameCLI SSL certificate keystore label = labelCLI SSL keystore pwd = password_file_name

Not FIPS-compliant (OpenSSL)CLI SSL server auth = yes|noCLI SSL cipher = cipher_classCLI SSL server certificate =certificate_file_nameCLI SSL trusted dir =trusted_directory

Store some or all of them in useroptsAs a minimum, the username and password parameters can be defined inthe user_home/.TWS/useropts file for the user who needs to make theconnection. Also, if you need to personalize for a user any of the propertiesnormally found in the localopts file, add the properties to the useroptsfile. The values in the useropts file always take precedence over those in


the localopts file. See “Setting user options” on page 41 for a fulldescription of the file and the properties.

The minimum set of properties you would find in useropts is as follows:username=user_IDpassword=password

Supply them when you use the commandWhen you use any of the commands you can add one or more of theconnection parameters to the command string. These parameters takeprecedence over the parameters in localopts and useropts. This allowsyou, for example, to keep the parameters in the localopts file and just getusers to supply the username and password parameters when they useone of the commands, avoiding the necessity to store this data in theuseropts file for each user..

The parameters can either be supplied fully or partially in a file, to whichyou refer in the command string, or typed directly as part of the commandstring. The full syntax is as follows:[-file <parameter_file>|[-host <host_name>][-password <user_password>][-port <port_number>][-protocol {http|https}][-proxy <proxy_name>][-proxyport <proxy_port_number>][-timeout <timeout>][-username <username>]

-file <parameter_file>A file containing one or more of the connection parameters.Parameters in the file are superseded if the correspondingparameter is explicitly typed in the command.

-host <host_name>The host name or IP address of the master domain manager towhich you want to connect.

-password <user_password>The password of the user supplied in the -username parameter.

-port <port_number>The listening port of the master domain manager to which youwant to connect.

-protocol {http|https}Enter either http or https, depending on whether you want tomake a secure connection.

-proxy <proxy_name>The host name or IP address of the proxy server involved in theconnection (if any).

-proxyport <proxy_port_number>The listening port of the proxy server involved in the connection (ifany).

-timeout <timeout>The number of seconds the command line client is to wait to makethe connection before giving a timeout error.


-username <username>The user ID of the user making the connection.

Note: From the command line, neither the default workstation, nor thecommand line client SSL parameters can be supplied. These mustalways be supplied in either the localopts (see “Setting localoptions” on page 23) or the useropts file for the user (see “Settinguser options” on page 41).

The command line client needs to assemble a full set of parameters, and itdoes so as follows:1. First it looks for values supplied as parameters to the command2. Then, for any parameters it still requires, it looks for parameters

supplied in the file identified by the -file parameter3. Then, for any parameters it still requires, it looks in the useropts file

for the user4. Finally, for any parameters it still requires, it looks in the localopts file

If a setting for a parameter is not specified in any of these places an erroris displayed.

Entering passwords

Password security is handled as follows:

Password entered in useropts fileYou type the connection password into the useropts file in unencryptedform. When you access the interface for the first time it is encrypted. Thisis the preferred method.

Password entered in the parameter file used by the commandYou type the connection password into the parameter file in unencryptedform. It is not encrypted by using the command. Delete the file after use toensure password security.

Password entered using the -password parameter in the commandYou type the password in the command string in unencrypted form. Itremains visible in the command window until you clear the commandwindow contents.

Note: On Windows workstations, when you specify a password that containsdouble quotation marks (") or other special characters, make sure that thecharacter is escaped. For example, if your password is tws11"tws, write it as"tws11\"tws" in useropts.

Tivoli Workload Scheduler console messages and promptsThe Tivoli Workload Scheduler control processes (Netman, Mailman, Batchman,Jobman, and Writer) write their status messages (referred to as console messages)to standard list files. These messages include the prompts used as job and jobstream dependencies. On UNIX and Linux operating systems, the messages canalso be directed to the syslog daemon (syslogd) and to a terminal running theTivoli Workload Scheduler console manager. These features are described in thefollowing sections.


Setting sysloglocal on UNIX

If you set sysloglocal in the local options file to a positive number, TivoliWorkload Scheduler's control processes send their console and prompt messages tothe syslog daemon. Setting it to -1 turns this feature off. If you set it to a positivenumber to enable system logging, you must also set the local option stdlistwidthto 0, or a negative number.

Tivoli Workload Scheduler's console messages correspond to the following sysloglevels:

LOG_ERRError messages such as control process abends and file system errors.

LOG_WARNINGWarning messages such as link errors and stuck job streams.

LOG_NOTICESpecial messages such as prompts and tellops.

LOG_INFOInformative messages such as job launches and job and job stream statechanges.

Setting sysloglocal to a positive number defines the syslog facility used by TivoliWorkload Scheduler. For example, specifying 4 tells Tivoli Workload Schedulertouse the local facility LOCAL4. After doing this, you must make the appropriateentries in the /etc/syslog.conf file, and reconfigure the syslog daemon. To useLOCAL4 and have the Tivoli Workload Scheduler messages sent to the systemconsole, enter the following line in /etc/syslog.conf:local4 /dev/console

To have the Tivoli Workload Scheduler error messages sent to the maestro and rootusers, enter the following command:local4.err maestro,root

The selector and action fields must be separated by at least one tab. Aftermodifying /etc/syslog.conf, you can configure the syslog daemon by entering thefollowing command:kill -HUP `cat /etc/syslog.pid`

console command

You can use the conman console command to set the Tivoli Workload Schedulermessage level and to direct the messages to your terminal. The message levelsetting affects only Batchman and Mailman messages, which are the mostnumerous. It also sets the level of messages written to the standard list file or filesand the syslog daemon. The following command, for example, sets the level ofBatchman and Mailman messages to 2 and sends the messages to your computer:console sess;level=2

Messages are sent to your computer until you either run another consolecommand, or exit conman. To stop sending messages to your terminal, enter thefollowing conman command:console sys


Enabling the time zone feature

Time zones are enabled by default on installation of the product.

When you upgrade, the time zone feature inherits the setting of the previousinstallation. You can enable the time zone using the enTimeZone option of theoptman command, as follows:optman chg enTimeZone = yes

The following steps outline the method of implementing the time zone feature:1. Load Tivoli Workload Scheduler.

The database allows time zones to be specified for workstations, but not onstart and deadline times within job streams in the database. The plan creation(JnextPlan) ignores any time zones that are present in the database. You willnot be able to specify time zones anywhere in the plan.

2. Define workstation time zones.Set the time zone of the master domain manager workstation, of the backupmaster domain manager, and of any agents that are in a different time zonethan the master domain manager. No time zones are allowed in the databasefor Start, Latest Start Time, and Termination Deadline times. No time zonesare allowed anywhere in the plan at this point, because enTimeZone is set tono.

3. When workstation time zones have been set correctly, enable the time zonefeature.All users are able to use time zones anywhere in the database, although theyshould wait for the next run of JnextPlan to use them on Start, Latest StartTime, and Termination Deadline times. The next time JnextPlan runs, timezones are carried over to the plan and the Dynamic Workload Console, and theback end allows specification of time zones anywhere in the plan.

4. Start using time zones on start and until times where needed.You can now use all time zone references in the database and in the plan withthe Dynamic Workload Console and the command-line interface.

Configuring to use the report commandsYou use the Tivoli Workload Scheduler report commands to obtain summary ordetailed information about your workload scheduling. Before using thesecommands, however, they must be configured for your environment. This processis described in the chapter on getting reports and statistics in the Tivoli WorkloadScheduler: User's Guide and Reference.

Modifying jobmon service rights for WindowsOn Windows systems, the Tivoli Workload Scheduler jobmon service runs in theSYSTEM account with the right Allow Service to Interact with Desktop granted toit. You can remove this right for security reasons. However, if you do so, itprevents the service from launching interactive jobs that run in a window on theuser's desktop. These jobs will be run, but are not accessible from the desktop orfrom Tivoli Workload Scheduler and do not have access to desktop resources. As aresult, they may run forever or abend due to lack of resources.


Chapter 3. Configuring the Dynamic Workload Console

This chapter describes how to configure Dynamic Workload Console. It is dividedinto the following sections:v “Launching in context with the Dynamic Workload Console”v “Configuring roles to access the Dynamic Workload Console” on page 84v “Configuring Dynamic Workload Console to use Single Sign-On” on page 87v “Configuring the use of Lightweight Third-Party Authentication” on page 88v “Configuring Dynamic Workload Console to use SSL” on page 92v “Customizing Dynamic Workload Console (Advanced configuration)” on page

92v “Configuring Dynamic Workload Console to view reports” on page 97v “Preventing a connection to specific Tivoli Workload Scheduler Version 8.3

engines” on page 99

Launching in context with the Dynamic Workload ConsoleThis chapter describes how to create a URL to launch the Dynamic WorkloadConsole and have it directly open the results of a particular query.

You can then include this URL in an external application, for example, to monitorjobs and job streams that are critical to your business, and to quickly and easilymanage them. You can access specific job or job stream details without having tocreate customized queries and monitor the state and health of the workstationsthat are critical in your environment so that, when unavailability or malfunctioningimpacts job scheduling, you are alerted.

ScenariosThe following main scenarios can be identified:v Obtain the result of a Monitor task on:

– Jobs– Critical jobs– Job streams

v Obtain the result of a Monitor task on workstationsv Obtain the result of a saved task.

For all the scenarios, you must create a basic URL as described in “Creating a basicURL.”

Creating a basic URL

To create a basic URL, perform the following steps:1. Define the URL to access the Dynamic Workload Console:

https://{WebUIHostname:adminSecurePort}/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false

where:


WebUIHostnameIt is the fully qualified hostname or the IP address of the computerwhere the Tivoli Dynamic Workload Console is installed.

adminSecurePortIt is the number of the port on which the Tivoli Dynamic WorkloadConsole is listening.

Examplehttps://mypc:29443/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false

2. Specify the action that you want to run, by specifying the correspondingparameter:

&actionIt indicates the action that you want to perform and can have one ofthe following values:v BrowseJobsv ZBrowseJobsv BrowseJobStreamsv BrowseCriticalJobsv BrowseWorkstationv InternalTask

3. Specify the engine on which you want to run the query, by entering itsparameters:

&hostnameFor distributed environments, it is the host name or TCP/IP address ofthe computer on which the Tivoli Workload Scheduler engine isinstalled. For z/OS environments, it is the host name or TCP/IPaddress of the computer on which the z/OS connector is installed.

&port The port number that is used to connect to the computer on which theTivoli Workload Scheduler engine or the z/OS connector is installed.Typically, the default port numbers are:

Table 19. Default port numbers

Port number Engine

31117 Tivoli Workload Scheduler distributed engine

31127 Tivoli Workload Scheduler for z/OS engine with z/OS connector V.8.3

31217 Tivoli Workload Scheduler for z/OS engine with z/OS connector V.8.5 orhigher

&serverIt applies to z/OS systems only and is mandatory. It is the name of theremote server of the engine as it was specified in the z/OS connector.

Example&hostname = webuidev&port = 31217&server = C851

Example of a complete URL:https://mypc:29443/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=BrowseJobs&hostname=webuidev&port=31117


Advanced optional parametersDepending on the query whose results you want to view, you can complete yourURL with the following parameters.

Monitor Jobs on distributed systemsCreate a URL by specifying the BrowseJobs action, as described in “Creating abasic URL” on page 77.

You can also specify any of the following filters:&workstation

Filter by the workstation on which the jobs runs.&jobstream

Filter by the job stream that contains the jobs.&job Filter by the job name.&schedtime

Filter by the job scheduled time.&status

Filter by the job status. You can filter by one or more statuses. Possiblevalues are:W WaitingO SuccessfulH HeldR ReadyE ErrorU UndecidedS RunningC CanceledB Blocked

&columnsSpecify the number of columns that you want to display in your resulttable. If not specified, the default number of columns for this query isshown. Supported values are:Min Display a minimum set of columnsAll Display all columns

Example:https://mypc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=BrowseJobs&hostname=webuidev&port=31117&workstation=my_ws&jobstream=my_js_name&job=my_job_name&status=ESB&columns=ALL

Monitor Jobs on z/OS systemsCreate a URL by specifying the ZBrowseJobs action, as described in “Creating abasic URL” on page 77.

You can also specify any of the following filters:

&workstationFilter by the workstation on which the job runs.

&jobstreamFilter by the job stream that contains the jobs.

&job Filter by the job name.

&schedtimeFilter by the job scheduled time.

Chapter 3. Configuring the Dynamic Workload Console 79

&columnsSpecify the number of columns that you want to display in your resulttable. If not specified, the default number of columns for this query isshown. Supported values are:

Min display a minimum set of columns

All display all columns

Example:https://mypc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=ZBrowseJobs&hostname=webuidev&port=31117&server=C851&workstation=my_ws&jobstream=my_js_name&job=my_job_name&schedtime=200812081100

Monitor Critical JobsCreate a URL by specifying the BrowseCriticalJobs action, as described in“Creating a basic URL” on page 77.


&workstationFilter by the workstation on which the job runs.

&jobstreamFilter by the job stream that contains the jobs.

&job Filter by the job name.

&schedtimeFilter by the job scheduled time.


Min Display a minimum set of columns

All Display all columns

Example:https://mypc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=BrowseCriticalJobs&hostname=webuidev&port=31117&workstation=my_ws&jobstream=my_js_name&job=my_job_name&server=C851&columns=Min

where &server is a parameter used for z/OS only.

Monitor Job StreamsCreate a URL by specifying the BrowseJobStreams action, as described in“Creating a basic URL” on page 77.


&workstationFilter by the workstation on which the job stream runs.

&jobstreamFilter by the job stream name.





Example:https://mypc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=BrowseJobStreams&hostname=webuidev&port=31117&workstation=my_ws&jobstream=my_js_name

Monitor WorkstationsCreate a URL specifying the BrowseWorkstation action, as described in “Creatinga basic URL” on page 77.


&workstationFilter by the workstation on which the job stream runs.




Example:https://mypc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=BrowseJobStreams&hostname=webuidev&port=31117&workstation=my_ws&jobstream=my_js_name&server=C851&columns=ALL

where &server is a parameter used for z/OS only.

Existing task

Create a URL by specifying the InternalTask action, as described in “Creating abasic URL” on page 77.

You can save this URL can be saved as a bookmark in your browser, so that, byclicking the bookmark, you can directly open the results of a previously createdtask.

To save a task URL, perform the following steps:1. Create a task with the Tivoli Dynamic Workload Console:


2. From the displayed panel, click the Add bookmark icon

to save this link in your bookmarks.3. Specify a name for the new bookmark. By default the task name is used.

Organize your bookmarks for your convenience, for example, you mightorganize your saved tasks in a different folder for each engine.

Example of a saved bookmark:https://cairapc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action=InternalTask&hostname=fferrar4&port=31117&taskname=All%20Jobs%20in%20plan%20for%20ferrari

Starting from this bookmark you can manually create a URL as follows:https://mypc:29043/ibm/console/xLaunch.do?pageID=com.ibm.tws.WebUI.External.navigation&showNavArea=false&action= InternalTask&hostname=webuidev&port=31117&server=C851 &taskname=myTask

Figure 1. List of tasks


where &server parameter is used for z/OS engines only.

Configuring access to the Dynamic Workload ConsoleAs soon as you finish installing the Dynamic Workload Console, you can launch itby using the link provided in the final installation panel.

However, after the installation, the administrator is the only user who can log intothe console, using the credentials specified during the installation.

This is the user defined in the Local OS user registry (for Windows) or in thecustom user registry (for UNIX).

There are two important steps an administrator must perform before other userscan log into and use the Dynamic Workload Consolev “Configuring a user registry”v “Configuring roles to access the Dynamic Workload Console” on page 84

If WebSphere Application Server is configured to use the local operating systemuser registry (the default value), users and groups must be created in the localoperating system. However, you can replace the local operating system userregistry with LDAP or a file registry, or configure the use of more than one ofthese.

Users defined in the user registry can log in to the Dynamic Workload Console;then they need to be associated to a role to be able access the Dynamic WorkloadConsole features (see ““Configuring roles to access the Dynamic WorkloadConsole” on page 84.)

By default, the Dynamic Workload Console on UNIX operating systems uses PAM(Pluggable Authentication Module) for authentication purposes. If you want toswitch to local OS authentication, perform the steps defined in “Configuring theDynamic Workload Console to use the local OS authentication method.”

Configuring a user registryIf WebSphere Application Server is configured to use LDAP user registry, usersand groups must be created by the system administrator in the chosen LDAPserver database.

Configuring user registries for the Dynamic Workload Console and all other TivoliWorkload Scheduler components is described in Chapter 5, “Configuringauthentication,” on page 139.

Configuring the Dynamic Workload Console to use the localOS authentication method

To modify the authentication method from PAM to local OS, perform the followingsteps:1. Login to the Dynamic Workload Console with WebSphere Application Server

administration credentials.2. Create a new user on the file registry clicking Manage users in the Dynamic

Workload Console portfolio (do not create it on the operative system).


|

||

||

||

||

|

|

|||||

||||

||||

|

|||

|||

|

|

||

||

||

3. Backup the WebSphere Application Server configuration using thebackupConfig command .

4. Dump your current security properties to a text file using the followingcommand:showSecurityProperties.sh > text_file

5. Customize the security properties by editing the file as follows:################################################################Global Security Panel################################################################enabled=trueenforceJava2Security=falseuseDomainQualifiedUserNames=falsecacheTimeout=600ltpaTimeOut=720issuePermissionWarning=falseactiveProtocol=CSIuseFIPS=falseactiveAuthMechanism=LTPAactiveUserRegistry=LocalOS

################################################################Federated Repository Panel################################################################PrimaryAdminId=new_userUseRegistryServerId=trueServerID=new_userServerPassword=new_pwdVMMRealm=TWSREALMVMMRealmDelimiter=@VMMIgnoreCase=true

6. Stop the server using the stopWas.sh wastool. To stop the server, use theWebSphere Application Server administration credentials.

7. Load the new properties using the following command:changeSecurityProperties.sh text_file

8. Restart the server using the startWas.sh wastool.

Configuring roles to access the Dynamic Workload ConsoleDuring the Dynamic Workload Console installation, new predefined roles arecreated in the Tivoli Integrated Portal. They determine which console panels areavailable to a user, and therefore which activities that user can perform fromDynamic Workload Console.

If you do not assign any of the predefined roles to a Tivoli Integrated Portal user,that user, after having logged in, will not see any entry for Tivoli WorkloadScheduler, and dynamic workload broker in the navigation tree.

Depending on the security repository you use, the following points apply:

LocalOSCreate the user in the operating system and assign the roles to that userusing the TIP console.

WIM Create the user using the TIP console. The user is a WAS user.

To create and assign roles, you must log into Tivoli Integrated Portal, expand Usersand Groups entry in Tivoli Integrated Portal navigation tree and click the entriesdisplayed below. For more information about creating and assigning roles, see theTivoli Integrated Portal online help by clicking the "?" (question mark) on top-rightcorner of the panels.


||

||

|

|

||||||||||||||||||||||||

||

|

|

|

|

||||

|||

|

|||

||

|||||

Tip It is not necessary to assign a role to every single user. If the user registryalready contains groups of users that are properly defined for using theconsole, it is possible to assign roles to groups too. If groups are notavailable in the user registry, then the special role all authenticated portalusers can be used to assign roles to all the users at once.

Within Tivoli Integrated Portal, you can create your own custom views to enableusers to see all or a subset of Tivoli Workload Scheduler pages. To do it, you musthave the iscadmins role and perform the following steps:1. Create a new Tivoli Integrated Portal View with the pages you want to be

available:a. In the Tivoli Integrated Portal portfolio, click Settings > Views.b. In the Views panel, click New and specify a name for the new view.c. Expand Pages in This View and click Add to add pages to the new view.d. Select the pages you want to be available to this view and click Add

2. Add the created view to the all authenticated portal users role:a. In the Tivoli Integrated Portal portfolio, click User and Groups > Roles.b. Click all authenticated portal users role.c. Expand Access to Views section, click the Add (plus sign) icon, select the

newly created view that you want to add to this role and click Add.d. Expand Access to Views and select the pages to which the users of this role

must have access.

The following lists the predefined roles created in the Tivoli Integrated Portal foraccessing the Tivoli Workload Scheduler environments using Dynamic WorkloadConsole, and the panels they can access:

TWSWEBUIAdministrator

Users in this group can use all features of the Dynamic Workload Console.They can see:All panels

TWSWEBUIOperator

Users in this group usually monitor and manage workload in the plan.They can see:v All Configured Tasksv Dashboardv Workload

– ForecastGenerate Trial PlanGenerate Forecast PlanList Available Plans

– SubmitSubmit Predefined Job StreamsSubmit Predefined JobsSubmit Ad Hoc Jobs

– Monitor- Monitor Jobs- Monitor Critical Jobs- Monitor Job Streams- Show Plan View- Workload Dependencies

Monitor FilesMonitor Resources


||||||

|||

||

|

|

|

|

|

|

|

||

||

|||

|

||

|

|||||||||||||||||||||

Monitor Prompts- Workload Events

Monitor Event RulesMonitor Operator MessagesMonitor Triggered Actions

v Scheduling Environment– Monitor

Monitor WorkstationsMonitor Domains

v SettingsManage User Preferences

TWSWEBUIDeveloper

Users in this group can create, list, and edit workload definitions,workstations, and event rule definitions in the Tivoli Workload Schedulerdatabase. They can see:v Workload

– DesignCreate Workload DefinitionsCreate Event RulesList Workload DefinitionsList Event RulesList Jobs on SAP


TWSWEBUIAnalyst

Users in this group can manage Dynamic Workload Console reports anduser preferences. They can see:v All Configured Reportsv Reporting

Generate Historical reportsGenerate Plan ReportsGenerate Custom SQL Reports


TWSWEBUIConfigurator

Users in this group can manage engine connections, user preferences, andscheduling environment design. They can see:v Scheduling Environment

– Design- Create Workstations- List Workstations

v SettingsManage EnginesManage User Preferences

Assigning a predefined role to an Tivoli Integrated Portal user allows that user toaccess the Dynamic Workload Console panels. The Tivoli Workload Scheduler userspecified in the engine connection, instead, determines which operations can berun locally on the connected Tivoli Workload Scheduler engine. For example, if theuser specified in a Tivoli Workload Scheduler engine connection is not authorizedto run reporting in the Tivoli Workload Scheduler Security file, then, even thoughthe Tivoli Integrated Portal user logged in to Dynamic Workload Console canaccess the reporting panels, he or she cannot perform reporting operations on that


|||||||||||

|

||||||||||||

|

|||||||||

|

|||||||||

||||||||

specific Tivoli Workload Scheduler engine. For more information about how toconfigure the security file, see “Configuring the security file” on page 106

The following lists the predefined roles created in the Tivoli Integrated Portal foraccessing the dynamic workload broker environments using Dynamic WorkloadConsole, and the panels they can access:

TDWBAdministratorAll panels

TDWBOperatorScheduling EnvironmentConfigurationDefinitions, except Define a New JobTrackingPreferences

TDWBDeveloperConfigurationDefinitionsPreferences

TDWBConfiguratorScheduling EnvironmentConfigurationTracking, except Job InstancesPreferences

Configuring Dynamic Workload Console to use Single Sign-OnSingle Sign-On (SSO) is a method of access control that allows a user toauthenticate once and gain access the resources of multiple applications sharing thesame user registry.

This means that using SSO you can run queries on the plan or manage objectdefinitions on the database accessing the engine without authenticating,automatically using the same credentials you used to login to the DynamicWorkload Console.

After the installation completes you can configure Dynamic Workload Console andthe Tivoli Workload Scheduler engine to use SSO. To do this they must share thesame LDAP user registry.

The Lightweight Directory Access Protocol (LDAP) is an application protocol forquerying and modifying directory services running over TCP/IP - see Chapter 5,“Configuring authentication,” on page 139 for more details.

If you configured Dynamic Workload Console to use Single Sign-On with anengine, then, the following behavior is applied:

If engine connection has the user credentials specified in its definitionsThese credentials are used. This behavior regards also engine connectionsthat are shared along with their user credentials.

If the user credentials are not specified in the engine connectionThe credentials you specified when logging in to Dynamic WorkloadConsole are used. This behavior regards also shared engine connectionshaving unshared user credentials.


||

|||

||

||||||

||||

|||||

LTPA token-keysIn addition to sharing the same LDAP user registry, the instance of WebSphereApplication Server that supports the Dynamic Workload Console and also theinstance which supports the engine where the Single Sign-On is required, mustboth be configured to use the same Lightweight Third-Party Authenticationtoken-keys. See “Configuring the use of Lightweight Third-Party Authentication”

Configuring the use of Lightweight Third-Party Authentication

The WebSphere Application Server uses the Lightweight Third-PartyAuthentication (LTPA) mechanism to propagate user credentials.

Depending on your circumstances, you might need to configure the use of thesame LTPA token_keys between Dynamic Workload Console and the engine, ordisable the automatic generation of the LTPA token_keys, or both:

Configuring for Single Sign-OnIf you are configuring for Single Sign-On, between any version of DynamicWorkload Console and any engine, whether or not they are installed on thesame system, you must configure both instances of WebSphere ApplicationServer involved to use the same LTPA token_keys, and disable theirautomatic regeneration on expiry, following the procedures described in:v “Configuring to use the same LTPA token_keys” on page 89v “Disabling the automatic generation of LTPA token_keys” on page 91

More than one instance of WebSphere Application Server on one systemIn this case you must use the same LTPA token_keys on all the applicationson the system that use a version of WebSphere Application Server (forexample, the Dynamic Workload Console and the Tivoli WorkloadScheduler engine, regardless of their versions), even if you are notimplementing Single Sign-On. You must also disable their automaticregeneration on expiry. Whether you need to take any action depends onwhich multiple instances of WebSphere Application Server are involved:

Multiple instances of the embedded WebSphere Application Serverfreshly installed in multiple Tivoli Workload Automation instances

In any system, if you have installed more than one instance of theembedded WebSphere Application Server (for example, DynamicWorkload Console and Tivoli Workload Scheduler in differentinstances of Tivoli Workload Automation) they will by default usethe same keys, so you only need to take an action to use the samekeys if you need to change them for any reason. However, youmust disable the automatic regeneration on expiry, following theprocedure described in:v “Disabling the automatic generation of LTPA token_keys” on

page 91

Other multiple instances of the WebSphere Application ServerIn any other circumstances where two instances of WebSphereApplication Server are installed on the same system (for example,you have installed Dynamic Workload Console on an externalWebSphere Application Server and a Tivoli Workload Schedulercomponent in a Tivoli Workload Automation instance on the samesystem, or you have installed a new instance of Dynamic WorkloadConsole to work with a previous version of Tivoli Workload


Scheduler, or vice versa), you must yourself ensure that allinstances use the same keys, and disable their automaticregeneration on expiry, following the procedures described in:v “Configuring to use the same LTPA token_keys”v “Disabling the automatic generation of LTPA token_keys” on

page 91

No Single Sign-On, and only one instance of WebSphere Application Server ona system

No action need to be taken.

Configuring to use the same LTPA token_keys

To use the same LTPA token_keys between WebSphere Application Servers, youmust run this procedure between Dynamic Workload Console and each engine youwant to connect to.

The LTPA token_keys can be either exported from Dynamic Workload Console andimported into the engine, or exported from the engine and imported into DynamicWorkload Console.1. Use the following script to export the LTPA token_keys from the WebSphere

Application Server where the Dynamic Workload Console is installed, and toimport them into the other instance of WebSphere Application Server:

Tivoli Workload Scheduler and Tivoli Dynamic Workload Console, Version8.5, 8.5.1, and 8.6

<TWA_home>/wastools/manage_ltpa.sh or ...\manage_ltpa.bat

Tivoli Workload Scheduler, Version 8.4<TWA_home>/wastools/manage_ltpa.sh or ...\manage_ltpa.bat

Tivoli Dynamic Workload Console, Version 8.4tdwc_install_dir\_tdwcutils\scripts\manage_ltpa.sh or...\manage_ltpa.cmd

Tivoli Workload Scheduler and Tivoli Dynamic Workload Console, Version8.3 For information relating to these releases see the relevant product

documentation.There is also a copy of manage_ltpa.sh and manage_ltpa.bat on eachinstallation image.Make sure that the user who runs this script is allowed to access theWebSphere Application Server profile that hosts the Dynamic WorkloadConsole or the engine.The syntax used to run the script is the following:manage_ltpa -operation import|export -profilepath profile_path

-ltpafile LTPA_file_path -ltpapassword LTPA_file_password-user username -password password-port SOAP_port -server server_name

where:

–operationSelect export to read the LTPA token_keys from the profile and save itto a file. Select import to update the profile with the LTPA token_keysstored in a file.


–profilepathSpecify the path to the profile on top of which the application, eitherDynamic Workload Console or Tivoli Workload Scheduler is installed.

–ltpafileSpecify the fully qualified path name of the file that contains, if youimport, or where to encrypt, if you export, the LTPA token_keys.

–ltpapasswordSpecify a password of your choice to encrypt the file that contains theLTPA keys when exporting them, or, when importing them, thepassword that was used to encrypt them when they were exported.This password is used only when importing and exporting that LTPAtoken_keys. It does not need to match the administrator password.

–user The administrator of the server hosting the Dynamic Workload Consoleor the engine. In the case of Tivoli Workload Scheduler, theadministrator is, by default, the owner of the instance (TWS_user).

–passwordThe password of the administrator of the server defined in the selectedprofile.

–port Specify the SOAP port used by the profile. By default the SOAP port is28880 for Dynamic Workload Console installed on the embeddedWebSphere Application Server, and 31118 for Tivoli Workload Schedulerinstalled on the embedded WebSphere Application Server.

–serverSpecify the name of the server of the profile on which to import orexport the LTPA tokens. The default server name varies, depending onhow it was installed. See Table 20.

Note:

a. The server and path might have been modified from thedefault value after installation.

b. This keyword is mandatory if the Tivoli Workload Schedulerserver name is different from the Dynamic Workload Consoleserver name.

Table 20. Product versions and default server names

Product versionWebSphere Application Serverversion Default server name

Tivoli WorkloadScheduler, V8.5and 8.5.1:

The embedded WebSphereApplication Server installed in aninstance of Tivoli WorkloadAutomation (on which any TivoliWorkload Scheduler component,including the Dynamic WorkloadConsole is installed).

twaserver<n>, found in the following path:

<TWA_home>/eWAS/profiles/TIPProfile/config/cells/DefaultNode/nodes/DefaultNode/servers

Your external version of theWebSphere Application Server, onwhich the Dynamic WorkloadConsole is installed.

server1, found in the appropriate path of your externalversion of WebSphere Application Server


Table 20. Product versions and default server names (continued)

Product versionWebSphere Application Serverversion Default server name

Tivoli WorkloadScheduler, V8.4and before:

The embedded WebSphereApplication Server on which TivoliWorkload Scheduler is installed.

server1, found in the following path:

<TWS_home>/appserver/profiles/twsprofile/config/cells/DefaultNode/nodes/DefaultNode/servers

The embedded WebSphereApplication Server on which theDynamic Workload Console isinstalled.

tdwcserver, found in the following path:

<tdwc_install_dir>/AppServer/profiles/tdwcprofile/servers

Your external version of theWebSphere Application Server, onwhich the Dynamic WorkloadConsole is installed.

server1, found in the appropriate path of your externalversion of WebSphere Application Server

2. Stop and start each server involved in this activity to enable it.3. If you are configuring Single Sign-On, test that the configuration is correctly set

between and the engine by performing the following steps:a. Log in to Dynamic Workload Console.b. Create an engine connection without specifying User ID and password.c. Perform a test connection.

The next step is to disable the automatic generation of the LTPA token_keys, forwhich see: “Disabling the automatic generation of LTPA token_keys”

Disabling the automatic generation of LTPA token_keys

Disable the automatic generation of LTPA token_keys, in either of the followingcircumstances:v You are enabling Single Sign-Onv You have more than one instance of WebSphere Application Server on the same

system

You must disable the generation of the keys at both ends of the communication, inother words, at the Dynamic Workload Console, and at the engine of TivoliWorkload Scheduler or dynamic workload broker, as appropriate:

At the Dynamic Workload Console

1. Log in to Dynamic Workload Console.2. Click Settings > WebSphere Administrative Console > Launch

WebSphere > Administrative Console.3. On WebSphere Administrative Console, click SSL certificate and key

management.4. Click the Key set groups link.5. Click on the name of the key set group displayed in the list.6. Clear the Automatically generate keys check box.7. Click OK.8. Check in the list that the field Automatically generate keys beside the

available key set group is set to false.

At Tivoli Workload SchedulerThe implementation of the embedded WebSphere Application Server onthe Tivoli Workload Scheduler engine includes a limited functionality


version of the Tivoli Integrated Portal. Use this portal to disable theautomatic generation of LTPA token_keys, as follows:1. Connect to the Tivoli Integrated Portal from an Internet browser, using

the following URL:http://TWS_server_hostname:WAS_admin_host_(secure_)port/ibm/console

Use the showHostProperties tool to identify the WAS_admin_host_port(default 31123) or WAS_admin_host_secure_port (default 31124), asappropriate. For more information about this tool, refer to “Applicationserver - using the utilities that change the properties” on page 312.

2. Perform the procedure you used above to disable the token-keysgeneration for the Dynamic Workload Console, starting from step 2 onpage 91.

Configuring Dynamic Workload Console to use SSLThe Secure Sockets Layer (SSL) protocol provides secure communications betweenremote server processes or applications. SSL security can be used to establishcommunications inbound to, and outbound from, an application. To establishsecure communications, a certificate, and an SSL configuration must be specifiedfor the application.

Full details are supplied in Chapter 7, “Setting connection security,” on page 183

Customizing Dynamic Workload Console (Advanced configuration)

Optionally, you can configure some advanced settings of Dynamic WorkloadConsole to customize its behavior. To do it, you must specify your settings in acustomizable file named TdwcGlobalSettings.xml, which you must then copy it inthe Dynamic Workload Console installation structure.

When you modify this file, stop and restart the Dynamic Workload Console tomake the changes effective in your environment.

Customizing your global settings

Users with Administrator privileges can use a configuration file, namedTdwcGlobalSettings.xml, to add and modify some customizable information.

A template of this file is located on the installation DVD underWEBUI/platform_name/utils. You can modify it, replacing default values withcustomized ones and enabling commented sections. After customizing, you mustcopy it under the following path: Installation_dir/TWA/eWAS/profiles/TIPProfile/registry directory.

This file is accessed at each login, and all configurations specified in the file areimmediately applied, except for precannedTaskCreation property. This property isread only when a user logs in for the first time and then is used whenever thisuser logs in again.

You can use any text or XML editor to edit this file, but ensure that you save it isas a valid XML file.

The file is organized into several sections that group similar properties.


|

||||

||

|

||

|||||

||||

||

|

Sections can also be repeated multiple times in the same file and applieddifferently to different user roles; however, for each role, you cannot have morethan one section associated. To apply a section only to the users belonging to aspecific role, the section must be included within the following setting:

settings roleThe user for which the following configuration must be applied. Defaultvalue: all users, unless otherwise specified.

Only one settings section can be specified for each role. If a user has more thanone role, the settings associated to the higher role are taken into consideration.

Example:<settings><graphViews><property name="planViewNewWindow" value="true"/></graphViews></settings>

<settings role="TWSWEBUIOperator"><graphViews><property name="planViewNewWindow" value="false"/></graphViews></settings>

graphViews

The graphViews section contains the configuration parameters that apply to thegraphical views in the plan, such as the maximum number of objects shown ineach view.

planViewMaxJobstreamsThe maximum number of job streams displayed in the Plan View. Defaultvalue is 1000.

jobstreamViewLimitThe maximum number of objects displayed in the Job Stream View. Defaultvalue is 1000.

impactViewLimitThe maximum number of job streams displayed in the Impact View.Default value is 2000.

planViewNewWindowSet it to TRUE if you want the plan view to be displayed in a newwindow each time it is launched. Default value is FALSE.

NewsFeed

The NewsFeed section contains the configuration details to be constantlyup-to-date with product information.

FeedURLContains the URL from which you receive news and updates. Defaultvalue is the product's Information Center at: http://publib.boulder.ibm.com/infocenter/tivihelp/v47r1/index.jsp?topic=/com.ibm.tivoli.itws.doc_8.6/welcome_TWA.html

PollIntervalThe interval in seconds between two checks for updates. Default value is3600.


||||

|||

||

|

|||||||||||

|

|||

|||

|||

|||

|||

|

||

|||||

|||

http://publib.boulder.ibm.com/infocenter/tivihelp/v47r1/index.jsp?topic=/com.ibm.tivoli.itws.doc_8.6/welcome_TWA.html



FeedTypeA string that identifies the type of update. Default value is JSONP.

application

The application section defines the environment for which predefined tasks arecreated

precannedTaskCreationSome predefined tasks are created by default and are available when youlog in to the console. There is a predefined Monitor task for every object,for both z/OS and distributed engines. Default value is all. To change thissetting, use one of the following values:v allv distributedv zosv none

help

The help section indicates the address of the current version of the InformationCenter.

infocenterURLThe URL of the Information Center. Default value is: http://publib.boulder.ibm.com/infocenter/tivihelp/v47r1/index.jsp?topic=/com.ibm.tivoli.itws.doc_6/welcome.html/welcome_TWA.html.

security

Use this section to configure some properties related to the User Registry in use.

groupIdMapThe property is related to the groups of User Registry, and can be modifiedto map and display the specified value of each group. The default is thecommon name of the group.

Examples:<settings>

<security><property name="groupIdMap" value="cn"></property>

</security></settings>

Therefore, if you need to change the default value "cn" to "racfid", you can definethis property as follows:<property name="groupIdMap" value="racfid"></property>

twsObjectDoc

The twsObjectDoc section contains URLs where you can store customizeddocumentation about your jobs or job streams. By default this setting is notspecified. If you want to associate customized documentation to a job or jobstream, use this setting to specify the external address where this information islocated. When you specify this setting, an action to access the relevantdocumentation becomes available from More Actions menus in Monitor Jobs andMonitor Job Streams tasks as well as in the graphical views in the plan (in the


||

|

||

|||||

|

|

|

|

|

||

||||

|

|

||||

|

|||||

||

|

|

|||||||




object's tooltips, context menus and properties) making it possible to open thedocumentation while monitoring your job or job stream in the plan.

To change this setting, use one of the following values:

customActionLabelThe name of the action displayed in menus, object properties, and tooltipsto access customized documentation about your jobs or job streams.

jobUrlTemplateThe address of your job documentation. No default value available.

jobstreamUrlTemplateThe address of your job stream documentation. No default value available.

These properties must be valid URLs, containing one or more of the variableslisted in the table below, as shown in the example:<settings>

<twsObjectDoc><property

name="jobstreamUrlTemplate"value="http://www.yourhost.com/tws/docs/jobstream/${js_name_w}" />

<propertyname="jobUrlTemplate"value="http://www.yourhost.com/docs/jobs/${job_name_w}" />

</twsObjectDoc></settings>

If you use any of the following special characters in the URL, you must write themas follows:

Table 21. Syntax for special characters

Special characters Write them as...

quote (") \"

apostrophe (') '

ampersand (&) &

less than (<) &lt

greater than (>) &gt

backslash (\) \\

Multiple variables can be included in a URL and must be specified using thefollowing syntax: ${variable}:

Table 22. Variables used in the URL definition

Name Object Description

job_number_w Job z/OS The number of the job

job_wkst_w Job The name of the workstationon which the job runs

job_jsname_w Job The name of the job streamthat contains the job

job_jswkst_w Job The name of the workstationon which the job stream runs


||

|

|||

||

||

||

||||||||||

||

||

||

||

||

||

||

||

|||

||

||

|||

|||

||||

||||

||||

Table 22. Variables used in the URL definition (continued)

Name Object Description

job_actualarrival_w Job z/OS The actual start time of thejob (date format:YYYY-MM-DDThh:mm:ss)

job_actualend_w Job z/OS When the job actuallycompleted (date format:YYYY-MM-DDThh:mm:ss)

job_starttime_w Job The start time of the job(date format:YYYY-MM-DDThh:mm:ss)

job_id_w Job The ID of the job

job_returncode_w Job The return code of the job

js_name_w Job stream The name of the job streamthat contains the job

js_wkst_w Job stream The name of the workstationon which the job stream runs

js_id_w Job stream The job stream ID

js_latest_start_w Job stream The latest time at which ajob stream can start (dateformat: YYYY-MM-DDThh:mm:ss)

engine_name_w Engine The name of the engineconnection

engine_host_w Engine The hostname of the engineconnection

engine_port_w Engine The port number of theengine connection

engine_plan_w Engine The ID of selected plan

engine_serv_w Engine The remote server name ofthe engine connection

TdwcGlobalSettings.xml sample

The following is a sample of the file:<settings role="TWSWEBUIOperator"><graphViews><property name="planViewMaxJobstreams" value="1000"></property><property name="jobstreamViewLimit" value="1000"></property><property name="impactViewLimit" value="1000"></property></graphViews></settings>

<settings role="TWSWEBUIAdministrator"><application><property name="precannedTaskCreation" value="all" />

</application></settings>

<settings><twsObjectDoc>

<propertyname="jobstreamUrlTemplate"


|

|||

|||||

|||||

|||||

|||

|||

||||

||||

|||

||||||

||||

||||

||||

|||

|||||

|

|

|||||||||||||||||||

value="http://www.yourhost.com/tws/docs/jobstream/${js_name_w}" /><property

name="jobUrlTemplate"value="http://www.yourhost.com/docs/jobs/${job_name_w}" />

</twsObjectDoc></settings>

Managing Dynamic Workload Console settings repositoryUser settings like user preferences, saved tasks and engine connections are storedin the settings repository, which by default is a local file. However, you can changethis setting and use the database settings repository for all Dynamic WorkloadConsole operations that involve user settings. This can be useful, for example, forscalability purposes or to have multiple Dynamic Workload Console instancessharing the same user settings.

To use a database as your settings repository, you must configure the databasesettings, as described in the sections about changing and sharing settingsrepository, in the Tivoli Workload Scheduler: Dynamic Workload Console User's Guide,available at the product's Information Center: http://publib.boulder.ibm.com/infocenter/tivihelp/v47r1/index.jsp?topic=/com.ibm.tivoli.itws.doc_6/welcome.html/welcome_TWA.html.

Configuring Dynamic Workload Console to view reportsThis topic describes the configuration steps that you perform to be able to see thereports from the Dynamic Workload Console.

To access the databases where reports are stored, you must have the followingprerequisites:v A user ID and password to access the databasev A working connection between the Dynamic Workload Console and the database

Perform the following steps on the system where the Tivoli Workload Schedulerengine is running:v “Configuring for a DB2 database”v “Configuring for an Oracle database” on page 98

Configuring for a DB2 database

For DB2, the IT administrator, or the Tivoli Workload Scheduler IT administrator,or both working together, do the following:1. Create an operating system user and specify a password.2. Launch the following script:

<TWA_home>/TWS/dbtools/DB2/scripts/dbgrant.bat/.sh<ID_of_user_to_be_granted><database_name>[<database_admin_user> <password>]

where the variables are as follows:

<TWA_home>The Tivoli Workload Automation instance directory


||||||

||

||||||

||||||




<ID_of_user_to_be_granted>The ID of the user created in step 1 on page 97, who is going to begranted the access to the reports

<database_name>The name of the database, as created when the master domain managerwas installed

[<database_admin_user> <password>]The user ID and password of the database administration user. If youare running this command as the database administration user, you canomit these parameters.

3. Log on to the Dynamic Workload Console.4. In the Portfolio, select Manage Engines. The Manage Engines panels is

displayed.5. Select the engine you defined or create another engine. The Engine Connection

properties panel is displayed.6. In Database Configuration for Reporting, do the following:

a. Check Enable Reporting to enable the engine connection you selected torun reports.

b. In Database User ID and Password, specify the database user andpassword that you authorized to access reports.

Configuring for an Oracle database

For Oracle, the IT administrator, or the Tivoli Workload Scheduler IT administrator,or both working together, do the following:1. Create a database user authorized to access the database and specify a

password.2. Launch the following script:

<TWA_home>/TWS/dbtools/Oracle/scripts/dbgrant.bat/.sh<ID_of_user_to_be_granted><database_name><database_admin_user> <password>

where the variables are as follows:

<TWA_home>The Tivoli Workload Automation instance directory

<ID_of_user_to_be_granted>The ID of the user created in step 1, who is going to be granted theaccess to the reports

<database_name>The name of the database, as created when the master domain managerwas installed

<database_schema_owner> <password>The user ID and password of the database schema owner.

3. Define a valid connection string to the database:a. Ensure that the following property is set in the <TWA_home>/eWAS/profiles/

TIPProfile/properties/TWSConfig.properties file to point to the OracleJDBC URL:com.ibm.tws.webui.oracleJdbcURL


For example:com.ibm.tws.webui.oracleJdbcURL=

jdbc:oracle:thin:@//9.132.235.7:1521/orcl

b. Restart the embedded WebSphere Application Server.4. Log on to the Dynamic Workload Console.5. In the Portfolio, select Manage Engines. The Manage Engines panels is

displayed.6. Select the engine you defined or create another engine. The Engine Connection

properties panel is displayed.7. In Database Configuration for Reporting, do the following:

a. Check Enable Reporting to enable the engine connection you selected torun reports.

b. In Database User ID and Password, specify the database user andpassword that you authorized to access reports.

Preventing a connection to specific Tivoli Workload Scheduler Version8.3 engines

Run the following script on Tivoli Workload Scheduler side if you want to disablethe ability to establish engine connections from Dynamic Workload Console to aTivoli Workload Scheduler Version 8.3 engine

On Windows:webui -operation disable

Run the script as Tivoli Workload Scheduler administrator, from thedirectory TWS_home\wastools:

On UNIX./webui.sh -operation disable

Run the script as root, from the directory TWS_home/wastools:

Restart the WebSphere Application Server on the Tivoli Workload Scheduler enginewhere you run the script.


Chapter 4. Configuring user authorization (Security file)

This chapter describes how to manage the authorizations to access schedulingobjects assigned to Tivoli Workload Scheduler users.

The chapter is divided into the following sections:v “Security management overview”v “Getting started” on page 102v “Updating the security file” on page 102v “Centralized security management” on page 105v “Configuring the security file” on page 106v “Sample security file” on page 133

Security management overviewThe way Tivoli Workload Scheduler manages security is controlled by aconfiguration file named security file. This file controls activities such as:v Linking workstations.v Accessing command-line interface programs and the Tivoli Dynamic Workload

Console.v Performing operations on scheduling objects in the database or in the plan.

In the file you specify for each user what scheduling objects the user is allowed toaccess, and what actions the user is allowed to perform on those objects. You candetermine access by object type (for example, workstations or resources) and,within an object type, by selected attributes, such as the object's name or theworkstation in the object's definition. You can use wildcards to select related sets ofobjects. Access rights can be granted on an "included" or an "excluded" basis, or acombination of both.

Whenever you need to change access permissions you modify the configurationfile and convert it into an encrypted format (for performance and security),replacing the previous file. The system uses this encrypted security file from thatpoint onwards.

Each time a user runs Tivoli Workload Scheduler programs, commands, and userinterfaces, the product compares the name of the user with the user definitions inthe security file to determine if the user has permission to perform those activitieson the specified scheduling objects.

By default, the security on scheduling objects is managed locally on eachworkstation. This means that the system administrator or the TWS_user whoinstalled the product on that system can decide which Tivoli Workload Schedulerusers defined on that system can access which scheduling resources in the TivoliWorkload Scheduler network and what actions they can perform.

Alternatively, you can centralize control of how objects are managed on eachworkstation. This can be configured by setting a global option. In this scenario,you configure all user permissions in the security file on the master domainmanager. The encrypted version of the file is distributed automatically every time


you run JnextPlan, so that all workstations have the file locally to determine thepermissions of the users on that workstation.

Getting startedThis section describes how to get started with defining authorizations afterinstallation.

A template file named TWA_home/TWS/config/Security.conf is provided with theproduct. During installation, a copy of the template file is installed asTWA_home/TWS/Security.conf, and a compiled, operational copy is installed asTWA_home/TWS/Security.

This version of the file contains a full access definition for the user who installedthe product, TWS_user, and the system administrator (root on UNIX orAdministrator on Windows), who are the only users defined and allowed toconnect to the user interfaces and to perform all operations on all schedulingresources.

Within the Tivoli Workload Scheduler network, using the security file you canmake a distinction between local root users and the root user on the masterdomain manager by allowing local root users to perform operations affecting onlytheir login workstations and providing the master domain manager root user theauthorizations to perform operations affecting any workstation across the network.

As you continue to work with the product you might want to add more users withdifferent roles and authorization to perform specific operations on a defined set ofobjects.

Do not edit the original TWA_home/TWS/config/Security.conf template, but follow the stepsdescribed in “Updating the security file” to make your modifications on the operationalcopy of the file.

Updating the security file

By default, every workstation in a Tivoli Workload Scheduler network (domainmanagers, fault-tolerant agents, and standard agents) has its own security file. Youcan maintain that file on each workstation, or, if you enable centralized securitymanagement you can create a security file on the master domain manager andcopy it to each domain manager and agent, ensuring that all Tivoli WorkloadScheduler users are assigned the required authorization in the file (see “Centralizedsecurity management” on page 105). Whether working on an agent workstation foran individual security file, or on the master domain manager to modify acentralized file, the steps are just the same; all that changes are the number ofusers you are defining - just those on the local system or all in the Tivoli WorkloadScheduler network.

Neither the Tivoli Workload Scheduler processes nor the WebSphere ApplicationServer infrastructure needs to be stopped or restarted to update the security file.You just need to close any open conman user interfaces before running makesec.

To modify the security file, perform the following steps:1. Navigate to the TWA_home/TWS directory from where the dumpsec and makesec

commands must be run.


2. Run the dumpsec command to decrypt the current security file into an editableconfiguration file. See “dumpsec.”

3. Modify the contents of the editable security configuration file using the syntaxdescribed in “Configuring the security file” on page 106.

4. Close any open conman user interfaces using the exit command.5. Stop any connectors on systems running Windows operating systems.6. Run the makesec command to encrypt the security file and apply the

modifications. See “makesec” on page 104.7. If you are using local security, the file will be immediately available on the

workstation where it has been updated.If you are using centralized security (see “Centralized security management”on page 105) you must now do the following:a. If you are using a backup master domain manager, copy the file to itb. Distribute the centralized file manually to all fault-tolerant agents in the

network (not standard, extended, or broker agents), and store it in theTWA_home/TWS directory

c. Run JnextPlan to distribute the Symphony file that corresponds to the newSecurity file

See the next pages for a full description of dumpsec and makesec.

dumpsec

Writes in an editable format the information contained in the compiled andencrypted security file. The output file can be edited and then used as input forthe makesec command which compiles and activates the modified securitysettings.

Authorization

You must have display access to the security file and write permission in theTWA_home/TWS directory from where the command must be run.

Syntax

dumpsec –v | –u

dumpsec security_file [> output_file]

Comments

If no arguments are specified, the operational security file is sent to stdout. Tocreate an editable copy of the security file, redirect the output of the command toan output file, using the redirect symbol.

Arguments

–v Displays command version information only.

–u Displays command usage information only.

security_fileSpecifies the name of the security file to dump.

Chapter 4. Configuring user authorization (Security file) 103

[> output_file]Specifies the name of the output file, If omitted, the security file is outputto the stdout.

Examples

The following command dumps the operational security file (TWA_home/TWS/Security) to a file named mysec:dumpsec > mysec

The following command dumps a security file named sectemp to stdout:dumpsec sectemp

makesec

Compiles security definitions and installs the security file. Changes to the securityfile are recognized as soon as makesec has completed, or, in the case of centralizedsecurity, after JnextPlan has distributed it.

Note: Before running the makesec command, stop conman, and, on systemsrunning Windows operating systems, any connectors.

Authorization

You must have modify access to the security file and read permission in theTWA_home/TWS directory from where the command must be run.

Syntax

makesec –v | –u

makesec [–verify] in_file

Comments

The makesec command compiles the specified file and installs it as the operationalsecurity file (../TWA_home/TWS/Security). If the –verify argument is specified, thefile is checked for correct syntax, but it is not compiled and installed.

Arguments

–v Displays command version information only.

–u Displays command usage information only.

–verifyChecks the syntax of the user definitions in in_file. The file is not compiledand installed as the security file.

in_file Specifies the name of a file or set of files containing user definitions.Syntax checking is performed automatically when the security file isinstalled.


Examples

Example 1: Modifying the security file definitions - full scenario

The following example shows how to modify the security file definitions:1. An editable copy of the operational security file is created in a file named

tempsec with the dumpsec command:dumpsec > tempsec

2. The user definitions are modified with a text editor:edit tempsec

3. The file is then compiled and installed with the makesec command:makesec tempsec

Example 2: Compiling user definitions from multiple files

The following command compiles user definitions from the fileset userdef* andreplaces the operational security file:makesec userdef*

Centralized security managementA Tivoli Workload Scheduler environment where centralized security managementis enabled is an environment where all workstations share the same security fileinformation contained in the security file stored on the master domain managerand the Tivoli Workload Scheduler administrator on the master domain manager isthe only one who can add, modify, and delete entries in the security file valid forthe entire Tivoli Workload Scheduler environment.

This is configured with the enCentSec global option. By default the value assignedto the enCentSec option is no.

To set central security management, the Tivoli Workload Scheduler administratormust run the following steps on the master domain manager:1. Use the optman command line program, to set the value assigned to the

enCentSec global property to yes. For information on how to manage the globalproperties using optman, see “Setting global options” on page 7.

2. Save the information in the security file into an editable configuration file usingthe dumpsec command.

3. Set the required authorizations for all Tivoli Workload Scheduler users, asdescribed in “Configuring the security file” on page 106

4. Close any open conman user interfaces using the exit command.5. Stop any connectors on systems running Windows operating systems.6. Compile the security file using the makesec command.7. If you are using a backup master domain manager, copy the compiled security

file to it as soon as possible.8. Distribute the compiled security file to all the workstations in the environment

and store it in their TWA_home/TWS directories.9. Run JnextPlan to update the security information distributed with the Symphony

file.The value of the checksum of the newly compiled security file is encrypted andloaded into the Symphony file and distributed to all the workstations in theTivoli Workload Scheduler network.


On each workstation, when a link is established or when a user connects to auser interface or attempts to issue commands on the plan, either with conmanor the Dynamic Workload Console, Tivoli Workload Scheduler compares thevalue of the checksum in the security file delivered with the Symphony file withthe value of the checksum of the security file stored on the workstation. If thevalues are equal, the operation is allowed. If the values are different, theoperation fails and a security violation message is issued.

Centralized security usage notesIn a network with centralized security management, two workstations are unableto establish a connection if one of them has enCentSec turned off in its Symphonyfile or if their security file information does not match.

The only exception to the security file matching criteria introduced by thecentralized security management mechanism is that a workstation must alwaysaccept incoming connections from its domain manager, regardless of the result ofthe security file matching process.

Centralized security does not apply to Tivoli Workload Scheduler operations forwhich the Symphony file is not required. Commands that do not require theSymphony file to run use the local security file. For example, the parms command,used to modify or display the local parameters database, continues to workaccording to the local security file, even if centralized security is active and thelocal security file differs from the centralized security rules.

If a workstation's security file is deleted and recreated, the checksum of the newsecurity file will not match the value in the Symphony file. In addition, arun-number mechanism associated with the creation process of the Symphony fileensures prevention from tampering with the file.

Configuring the security fileIn the security file you can specify which scheduling objects a user can manageand how. You define these settings by writing user definitions. A user definition isan association between a name and a set of users, the objects they can access, andthe actions they can perform on the specified objects.

When defining user authorization consider that:v When commands are issued from the composer command line program, the

user authorizations are checked in the security file of the master domainmanager since the methods used to manage the entries in the database areinvoked on the master domain manager. Therefore the user must be defined:– As system user on the system where the master domain manager is installed.– In the security file on the master domain manager with the authorizations

needed to run the allowed commands on the specific objects.v When commands are issued from the conman command line program, the user

must be authorized to run the specific commands in the security file both on theconnecting workstation and on the master domain manager where the commandactually runs.

The configuration is described in these sections:v “Security file syntax” on page 107v “Specifying user attributes” on page 108v “Specifying object types” on page 113


v “Specifying object attributes” on page 114v “Specifying access” on page 119v “The TWS_user - special security file considerations” on page 133

Security file syntax

The syntax of the security file is as follows:

Security fileSyntax

[# comment]

user definition_name user_attributes

begin [* comment]

object_type [object_attributes]. access[=keyword[,keyword]...]

[object_type [object_attributes]. access[=keyword[,keyword]...] ]...

end | continue

Arguments

[# | *] commentAll text following a pound sign or an asterisk and at least one space istreated as a comment. Comments are not copied into the operationalsecurity file installed by the makesec command.

user definition_nameSpecifies the name of the user definition. The name can contain up to 36alphanumeric characters and must start with an alphabetic character.

user_attributesContains one or more attributes that identify the user or users to whom thedefinition applies. For details of how to define user attributes, see“Specifying user attributes” on page 108.

begin Begins the part containing object statements and accesses within the userdefinition.

object_typeIdentifies the type of object (for example: workstation, resource, or prompt)to which access is to be given for the specified user or users. All objecttypes that the specified user or users needs to access must be explicitlydefined. If they are not, no access will be given. For details of how todefine object types, see “Specifying object types” on page 113.

object_attributesContains one or more attributes that identify the specific objects of thedefined object type to which the same access is to be given. If no objectattributes are defined, access is given to all objects of the defined objecttype. For details of how to define object attributes, see “Specifying objectattributes” on page 114.

access[=keyword[,keyword]...]Describes the access to the specified objects given to the selected users. Ifnone is specified (by specifying just the keyword "access") no access is


given to the associated objects. If access=@ then all access rights areassigned to the specified users. For details of how to define access, see“Specifying access” on page 119.

continueTerminates the user definition. A user gets all the accesses defined for eachgroup that they belong to, until a user definition with an end statement isreached. For an example of the use of the continue keyword, see “Userslogged in to multiple groups [continue keyword]” on page 137

end Terminates the user definition. The users defined in the user definition thatterminates with an end statement do not match any subsequent userdefinition.

Wildcards

The following wildcard characters are permitted in user definition syntax:

? Replaces one alphanumeric character.

@ Replaces zero or more alphanumeric characters.

For information about variables supplied with the product that can be used inobject attributes, refer to “Using variables in object attribute definitions” on page118. Refer to “Sample security file” on page 133 for an example on how to usevariables.

Specifying user attributesThe user attributes define who has the access that is going to be subsequentlydefined. They can identify one user, a selection of users, a group of users, aselection of groups of users, or all users. You can also exclude one or more specificusers or groups from a selection. As well as being identified by logon ID andgroup name, users can also be described by the workstation from which they logon. And finally, you can mix selection criteria, for example selecting all users in anamed group that can access from a set of workstations identified by a wildcard,but excluding a specific set of users identified by their logon IDs.

The general syntaxYou make this selection by specifying one or more user attributes. Each userattribute is specified as follows:

user_attribute_type=value

user_attribute_typeCan be cpu (workstation), group, or logon

value Identifies an individual cpu (workstation), group, or logon, or, by usingwildcards, can identify a set of any of these.

Including or excludingEach attribute can be included or excluded from the selection.

Thus, for each attribute type, your options are one of the following:

Include allThis is the default. Thus, for example, if you want to include all groups,you need add no user attribute with respect to any group.

Include a selectionThis can be defined in one of these ways:


v By specifically including users you want to select (individuals or one ormore sets)

v By specifically excluding (from the include all default) all users you donot want to select

v By specifically including a set of users and then excluding some of thosecontained in the set

Which of these options you choose is determined by which is easier tospecify.

Using the include or exclude symbols:

IncludePrecede the user attribute expression by a plus (+) sign. All users identifiedby the expression will be selected, unless they are also selected by anexclude expression. If the first attribute in your definition is an include, itdoes not need to have a (+) sign defined, because the sign is implicit.

The default (if you specify no user attributes) is to include all users, on allworkstations, in all groups, so if you want to define, for example, all usersexcept one named user, you would just supply the exclude definition forthe one user.

ExcludePrecede the user attribute expression by a tilde (~) sign. All users identifiedby the expression will never be selected, regardless of if they are identifiedby any include expressions.

Selection expressionsThe following are the different types of selection expression you can use:

Basis selection expressions

Include only one attributeuser_attribute_type=value

For example, to include one named user logon ID, and exclude allother users:logon=jsmith1

Exclude one attribute~user_attribute_type=value

For example, to exclude one set of logon IDs identified by awildcard (those that start with the letter "j"), but include all others:~logon=j@

Include only several attributes of the same typeuser_attribute_type=value[,value]...

For example, to include three specific users and exclude all others:logon=jsmith1,jbrown1,jjones1

Exclude several attributes of the same type~user_attribute_type=value[,value]...

For example, to exclude three specific users and include all others:~logon=jsmith1,jbrown1,jjones1

Complex selection expressions


Include users identified by different selection expressionsbasic_selection_expression[+basic_selection_expression]...

The selection expressions can be of the same or a different attributetype:

Same attribute typeAn example of the same attribute type is the following,which selects all the groups beginning with the letter "j", aswell as those with the letter "z":group=j@+group=z@

If the first selection identifies 200 users, and the second300, the total users selected is 500.

Different attribute typeAn example of selection expressions of a different attributetype is the following, which selects all the groupsbeginning with the letter "j", as well as all users with IDsbeginning with a "6":group=j@+logon=6@

If the first selection identifies 200 users, and the second 20,of whom 5 are also in the first group, the total usersselected is 5.

Exclude users identified in one selection expressions from thoseidentified in another

basic_selection_expression[~basic_selection_expression]...

Same attribute typeThe selection expressions can be of the same attribute type,provided that the second is a subset of the first. Anexample of the same attribute type is the following, whichselects all the workstations beginning with the letter "j", butexcludes those with a "z" as a second letter:group=j@~group=jz@

If the first selection identifies 200 users, and the second 20,the total users selected is 180. Note that if the secondexpression had not been a subset of the first, the secondexpression would have been ignored.

Different attribute typeSelection expressions of a different attribute type do nothave to have a subset relationship, an example being thefollowing, which selects the group "mygroup", but excludesfrom the selection all users in the group with IDsbeginning with a "6":group=mygroup~logon=6@

If the first selection identifies 200 users, and the second 20,of whom 5 are also in the first group, the total usersselected is 195.

Multiple includes and excludesYou can link together as many include and exclude expressions asyou need to identify the precise subset of users who require thesame access. The overall syntax is thus:


[~]user_attribute_type=value[,value]...[{+|~}user_attribute_type=value[,value]...

Note: Making your first user attribute an exclude means that all user attributes ofthat type are selected except the indicated value. Thus,~user_attribute_type=value equates to the following:

user_attribute_type=@~same_user_attribute_type=value

However, if you use this syntax, you cannot, and do not need to, specificallyadd "+user_attribute_type=@", after the negated item, so you do not define:

~user_attribute_type=value+same_user_attribute_type=@

Order of user definitionYou must order user definitions from most specific to least specific. TivoliWorkload Scheduler scans the security file from top-down, with each user ID beingtested against each definition in turn. If the user ID is satisfied by the definition, itis selected, and the matching stops.

For example:

Incorrect:#First User Definition in the Security FileUSER TwsUserCPU=@+LOGON=TWS_userBeginjob name=@ access=modifyEnd

#Second User Definition in the Security FileUSER Twsdomain:TwsUserCPU=@+LOGON=TWSDomain\\TWS_userBeginjob name=@ access=displayEnd

Note: The domain name is actually "TWSDomain\TWS_user", but it hasbeen "escaped", as described in “Escaping special characters in userattribute values” on page 113.

The definitions are intended to determine the following:1. Users on all workstations with a logon of "TWS_user" will be given

"modify" access to all jobs2. Users on all workstations with a logon of "TWSDomain\TWS_user"

will be given "display" access to all jobs

However, all users with a logon of "TWS_user" will satisfy the first rule,regardless of their domain, and will be given "modify" access to all jobs.This is because defining a user without its domain is a shorthand way ofdefining that user ID in any domain; it is the equivalent of "@\TWSUser".So the second rule will never be satisfied, for any user, because thematching for the "TWS_user" stops after a successful match is made.

Correct#First User Definition in the Security FileUSER Twsdomain:TwsUserCPU=@+LOGON="TWSDomain\\TWS_user"Beginjob name=@ access=displayEnd


#Second User Definition in the Security FileUSER TwsUserCPU=@+LOGON=TWS_userBeginjob name=@ access=modifyEnd

By putting the more specific definition first, both object access definitionsare applied correctly.

See “Sample security file” on page 133 for a practical example.

User attribute types - detailed descriptionThe user_attribute_types and their associated values can be any of the following:

cpu={workstation|@}where:

workstationSpecifies the workstation on which the user is logged in. Wildcardcharacters are permitted. The following Tivoli Workload Schedulervariables can be used:

$masterMeans that the user is logged in on the Tivoli WorkloadScheduler master domain manager.

$managerMeans that the user is logged in on the Tivoli WorkloadScheduler domain manager.

$remotesMeans that the user is logged in on any Tivoli WorkloadScheduler standard agent.

$slavesMeans that the user is logged in on any Tivoli WorkloadScheduler fault-tolerant agent.

$thiscpuMeans that the user is logged in on the Tivoli WorkloadScheduler workstation on which the security check isrunning.

@ Specifies that the user is accessing Tivoli WorkloadScheduler with the Tivoli Dynamic Workload Console, or islogged in on any Tivoli Workload Scheduler workstation.

group=groupnameSpecifies the name of the group of which the user is a member. Availablefor both UNIX and Windows users. Wildcard characters are permitted.

logon={username|@}where:

usernameSpecifies the user ID with which the user is logged in on a TivoliWorkload Scheduler workstation. Wildcard characters arepermitted. The cpu= attribute must be set to a specific workstationname (no wildcards) or @.

Note:


|||

1. If the WebSphere Application Server securityconfiguration option useDomainQualifiedUserNames isset to true, each user ID defined in the security file musthave the format domain/username to use the productfrom one of the following:v composer

v Tivoli Dynamic Workload Consolev logman

v optman

v planman

For more information on WebSphere Application Serversecurity configuration, see “Changing the securitysettings” on page 296.

2. If the user is defined on a Windows 2000 Service Pack 4(SP4), or Windows XP Service Pack 2 (SP2), or Windows2003 system, or when upgrading the Windows operatingsystem from an older version to one of those mentionedabove, make sure you add the Impersonate a client afterauthentication right to the user settings.

@ Specifies any user logged in with any name or being a member ofany Tivoli administrators group.

Escaping special characters in user attribute values

If you need to use a special character in the value field of a user attribute , youmust enclose the value in double quotes and escape the special character with aback slash. These are the special characters supported in this way:’"\space

This, if you want to include a group called wingrp\sales, you should enter:+group="wingrp\\sales"

Similarly, Wingroup Sales would be:+group="Wingroup\ Sales"

Specifying object typesSpecify one or more object types that the user or users in the associated userdefinition is authorized to access. If you specify the object type but no attributes,the authorized actions defined for the user with the access keyword apply to allthe objects of that type defined in the Tivoli Workload Scheduler domain. If anobject type from the following list is omitted for a user or users, no objects of thattype can be accessed.

The object types are the following:

action Actions defined in scheduling event rules

calendarsUser calendars

cpu Workstations, domains and workstation classes


event Event conditions in scheduling event rules

eventruleScheduling event rule definitions

file Tivoli Workload Scheduler database file

job Scheduled jobs and job definitions

parameterLocal parameters. See note below.

promptGlobal prompts

report The reports on the Dynamic Workload Console that have the followingnames:

RUNHISTJob Run History

RUNSTATSJob Run Statistics

WWS Workstation Workload Summary

WWR Workstation Workload Runtimes

SQL Custom SQL

ACTPRODActual production details (for current and archived plans)

PLAPRODPlanned production details (for trial and forecast plans)

Permission to use these reports is granted by default to the TWS_user onfresh installations.

resourceScheduling resources

scheduleJob streams

userobjUser objects

vartableVariable tables. This includes authorization to the variable definitions inthe tables. See the note below.

Note: Starting from version 8.5, the parameter object type is reserved forparameters created and managed in a local parameter database with theparms utility command, while authorization to act on global variables ismanaged using the vartable object type. For this reason, when the securityfile is migrated from previous versions to 8.5, a vartable security definitionfor the default variable table is added to match each parameter definitionfound, as part of the upgrade process documented in the Tivoli WorkloadScheduler: Planning and Installation Guide.

Specifying object attributesSpecify one or more attributes that identify a set of objects that the user of the userdefinition is authorized to access. If you specify the object type but no object sets,


the authorized actions defined for the user with the access keyword apply to allthe objects of that type defined in the Tivoli Workload Scheduler domain.

The general syntaxEach object attribute is specified as follows:

object_attribute=value

object_attributeObject attributes differ according to the object. All objects can be selectedby name, but some, jobs, for example, can be selected by the workstation onwhich they run. See “Object attribute” for full details of which attributesare available for each object type.

value Identifies an individual object, or, by using wildcards, a set of objects. See“Specifying object attributes” on page 114 for full details of whichattributes are available for each object type.

Object attribute“Specifying object attributes” on page 114 lists object attributes that are used toidentify a specific set of object within all objects of the same type. For example,access can be restricted to a set of resource objects having the same name or beingdefined on the same workstation, or both.

Table 23. Object attribute types for each object type

Attribute

name cpu custom jcl jcltype logon provider type host portObject

action U U U U

calendar U

cpu (workstation) U U

event U U U

eventrule U

file U

job U U U U U

parameter U U

prompt U

report U

resource U U

schedule (job stream) U U

userobj U U

vartable U

Including or excludingEach attribute can be included or excluded from the selection using the plus (+) andtilde (~) symbols, in the same way as for the user attributes.

Selection expressionsThe detailed syntax and use of the selection expressions for objects is the same asthat used to select users:

[~]object_attribute=value[,value]...[{+|~}object_attribute=value[,value]...


|

Order of object definitionYou must order object definitions from most specific to least specific, in the sameway as for user attributes. For example,

Incorrectjob name=@ access=displayjob name=ar@ access=@

In this case, a job with the name beginning with "ar" would satisfy the firstdefinition, and so would be given the display access, not all access.

Correctjob name=ar@ access=@job name=@ access=display

Ensure that you order object definitions from most specific to least specific alsowhen you use the Continue keyword. With this keyword, you match more userdefinitions to a single user, so the user receives accesses from more user definitionstatements. These accesses are then processed in the order they are written in thesecurity file. For an example of a security file with the Continue keyword, see“Users logged in to multiple groups [continue keyword]” on page 137

Specifying object attribute valuesThe following describes the values allowed for each object attribute type:

name=name[,name]...Specifies one or more names for the object type. Wildcard characters arepermitted. Multiple names must be separated by commas.v The following values apply to the file object type:

globaloptsAllows the user to set global options with the optman command.Gives the following access types:– Display access for optman ls and optman show– Modify access for optman chg

prodskedAllows the user to create, extend, or reset the production plan.

securityAllows the user to manage the security file.

SymphonyAllows the user to run stageman and JnextPlan.

trialskedAllows the user to create trial and forecast plans or to extendtrial plans.

Note: Users who have restricted access to files should be given at leastthe following privilege to be able to display other objects (ie.calendars and cpus):file name=globalopts access=display

v For the event object type use one or more of the event type names listedin the TWSObjectsMonitor events table or the FileMonitor events table inthe Tivoli Workload Scheduler: User's Guide and Reference.

v For the action object type use one or more of the action type nameslisted in the table Action types by action provider in the Tivoli WorkloadScheduler: User's Guide and Reference.


||||||

v For the vartable object type, you can use the $DEFAULT value for thename attribute to indicate the default variable table. This selects thetable defined with the isdefault attribute.

cpu=workstation[,workstation]...Specifies one or more workstation, domain, or workstation class names.Wildcard characters are permitted. Multiple names must be separated bycommas. If this attribute is not specified, all defined workstations anddomains can be accessed. Workstation variables can be used - see “Usingvariables in object attribute definitions” on page 118.

custom=value[,value]...

Use this attribute to assign access rights to events defined in eventplug-ins. The precise syntax of the value will depend on the plug-in. Forexample:v Specify different rights for different users based on SAP R/3 event

names when defining event rules for SAP R/3 events.v Define your own security attribute for your custom-made event

providers.v Specify the type of event that is to be monitored. Every event can be

referred to an event provider.

jcl="path" | "command"Specifies the command or the path name of a job object's executable file.The command or path must be enclosed in double quotes ("). Wildcardcharacters are permitted. If omitted, all defined job files and commandsqualify.

jcltype=[scriptname | docommand]Specifies that the user is allowed to act on the definitions of jobs that runonly scripts (if set to scriptname) or commands (if set to docommand). Usethis optional attribute to restrict user authorization to actions on thedefinitions of jobs of one type or the other only. Actions are granted forboth scripts and commands when jcltype is missing.

A user who is not granted authorization to work on job definitions thatrun either a command or a script is returned a security error messagewhen attempting to run an action on them.

logon=username[,...]Specifies the user IDs. Wildcard characters are permitted. Multiple namesmust be separated by commas. If omitted, all user IDs qualify. For the jobtype object, the following variables are permitted: $jclowner, $owner, and$user (see “Using variables in object attribute definitions” on page 118).

provider=provider_name[,...]

For action object types, specifies the name of the action provider.

For event object types, specifies the name of the event provider.

Wildcard characters are permitted. Multiple names must be separated bycommas. If provider is not specified, no defined objects can be accessed.

type=type[,...]

For action object types, is the actionType.

For event object types, is the eventType.


For cpu object types, the permitted values are those used in composer orthe Dynamic Workload Console when defining workstations, such asmanager, broker, fta, agent, s-agent, x-agent, rem-eng, pool, and d-pool.

Note: The value master, used in conman is mapped against the managersecurity attributes.

Wildcard characters are permitted. Multiple names must be separated bycommas. If type is not specified, all defined objects are accessed for thespecified providers (this is always the case after installation or upgrade, asthe type attribute is not supplied by default).

host=host_nameFor action object types, specifies the TEC or SNMP host name (used forsome types of actions, such as sending TEC events, or sending SNMP). If itdoes not apply, this field must be empty.

port=port_numberFor action object types, specifies the TEC or SNMP port number (used forsome types of actions, such as sending TEC events, or sending SNMP). If itdoes not apply, this field must be empty.

Using variables in object attribute definitionsThe following variables supplied with the product can be used in object attributes:

User identifiers

$jclgroupThe group name of a job's executable file.

$jclownerThe owner of a job's executable file.

$ownerThe creator of a job stream and its jobs.

$user The user running the Tivoli Workload Scheduler command orprogram.

Note: The variables $jclgroup and $jclowner can only be verified if theuser is running a Tivoli Workload Scheduler program on theworkstation where the job's executable file is present. If the programis being run on a different workstation, the user is denied access.

Workstation identifiers

$masterThe Tivoli Workload Scheduler master domain manager.

$managerThe Tivoli Workload Scheduler domain manager.

$remotesAll standard agent workstations.

$slavesAll fault-tolerant agent workstations.

$thiscpuThe workstation on which the user is running the Tivoli WorkloadScheduler command or program.

Variable table identifiers


|||

||

|

||

||

||

||

|||

$defaultThe name of the current default variable table.

Specifying access

Specify the type of access the selected users are allowed to have to the specifiedobjects as follows:

access[=keyword[,keyword]...]v To specify that no actions are permitted, use access=

v To specify that all actions are permitted, use access=@

v To specify any other access, consult the access tables, by object type, below.

How the access tables are organized

The access tables for object types are as follows:

“Object types - calendar, cpu, eventrule, job, prompt, resource, schedule, userobj- using in composer” on page 120

Most of the composer and GUI database maintenance actions are commonto most objects, so they are listed in a table of common object accesskeywords.

“Object type - action” on page 122This gives the access rights for action objects, which are not included in thecommon table.

“Object type - calendar” on page 123This gives the access rights for calendars, which are different or additionalto those in the common table.

“Object type - cpu” on page 123This gives the access rights for workstations (cpus), which are different oradditional to those in the common table.

“Object type - event” on page 125This gives the access rights for events, which are different or additional tothose in the common table.

“Object type - file” on page 125This gives the access rights for files, which are different or additional tothose in the common table.

“Object type - job” on page 125This gives the access rights for jobs, which are different or additional tothose in the common table.

“Object type - parameter” on page 128This gives the access rights for local parameters, which are not included inthe common table.

“Object type - prompt” on page 129This gives the access rights for prompts, which are different or additionalto those in the common table.

“Object type - report” on page 130This gives the access rights for reports, which are different or additional tothose in the common table.


“Object type - resource” on page 130This gives the access rights for resources, which are different or additionalto those in the common table.

“Object type - schedule” on page 130This gives the access rights for job streams (schedules), which are differentor additional to those in the common table.

“Object type - userobj” on page 131This gives the access rights for userobj, which are different or additional tothose in the common table.

“Object type - vartable” on page 132This gives the access rights for variable tables, which are not included inthe common table.

Object types - calendar, cpu, eventrule, job, prompt, resource,schedule, userobj - using in composer

The following table gives the access keywords required to use composer to workwith objects of the following types:v calendarv cpuv eventrulev jobv promptv resourcev schedulev userobj

Note: Starting from version 8.5, the parameter keyword is reserved for parameterscreated and managed in a local parameter database with the parms utilitycommand. For more information about parms, see User's Guide and Reference.


Table 24. Access keywords for composer actions

Activity

Accesskeywordsrequired

Composer add Add new object definitions in the database from a file ofobject definitions. Unlock access is needed to use the;unlock attribute.

add,modify,unlock

create Create a text file of object definitions in the database.Modify access is need to use the ;lock attribute.

display,modify

delete Delete object definitions from the database. delete

display Display object definitions in the database. display

extract Extract a text file of object definitions from the database. display

list List object definitions in the database. display

lock Lock object definitions in the database. modify

modify Modify object definitions in the database. Definitions areextracted into a file. After you have edited the file thedefinitions are used to replace the existing ones.

add,modify

new Create object definitions in the database from a template. add,modify

print Print object definitions in the database. display

rename Rename object definitions in the database. You need addaccess to the new object and delete and display access tothe old object.

add, delete,display

replace Replace object definitions in the database. Unlock access isneeded to use the ;unlock attribute.

add,modify,unlock

unlock Unlock object definitions in the database. unlock


Table 24. Access keywords for composer actions (continued)

Activity


Tivoli DynamicWorkload Console

Create object indatabase

Add new object definitions in the database. add

Delete object indatabase

Delete object definitions from the database. Unlock accessis needed to use the ;unlock option.

delete

Display object indatabase

Display object definitions in the database. display

List object in database List object definitions in the database. display

Modify object indatabase

Modify object definitions in the database. Unlock access isneeded to use the ;unlock option.

modify

Unlock object indatabase

Unlock object definitions in the database locked byanother user.

unlock

Perform operationsfor job types withadvanced options,both those suppliedwith the product andthe additional typesimplemented throughthe custom plug-ins.You can define andperform operationson job types withadvanced optionswith the WorkloadDesigner.

Perform operations for job types with advanced options inthe database.

run

Using theworkload serviceassurance feature

All activities For any user to perform any workload service assuranceactivities, the TWS_user must have the following accesskeywords for all cpu, job, and schedule objects:

display,modify, list

Example: To allow a user to use the composer list, display, and modify actions onevent rules, specify:eventrule access=add,display,modify

Object type - action

The following table gives the access keywords required for actions:

Table 25. Actions - access keywords

Activity


Tivoli Dynamic Workload Console Display action instances display

List action instances. list


||||||||||||||

|||

Table 25. Actions - access keywords (continued)

Activity


Tivoli Dynamic Workload Console

conman

Use these specific action types in event rule definitions.

v For actions with provider TWSAction and types sbj, sbd, orsbs, you must set this keyword in combination with thesubmit access keyword for the specific jobs and job streamsspecified in the action.

v For actions with provider TWSAction and type reply, youmust set this keyword in combination with the reply accesskeyword set for the specific prompts specified in the action.

The TWS_user of the workstation running the event processingserver must have these submit and reply authorizations,otherwise the event processing server will not be able to runthis type of actions.

use

Example: To allow a user to use the Tivoli Dynamic Workload Console to listaction instances, specify:action access=list

Object type - calendar

The following table gives the additional access keywords required to work withcalendars, other than those described in Table 24 on page 121:

Table 26. Calendar - additional access keywords

Activity


Composer


Use calendars in job streams use

Example 1: To allow a user to only use calendars when working with job streamsin any of the interfaces, specify:calendar access=use

Example 2: To allow a user to display, list, and print calendars, and use themwhen working with job streams in any of the interfaces, specify:calendar access=display,use

Object type - cpu

The following table gives the additional access keywords required to work withcpus (includes workstations, domains, and workstation classes), other than thosedescribed in Table 24 on page 121:


Table 27. Cpus - additional access keywords

Activity


Conman


console View and send messages to the Tivoli WorkloadScheduler conman console.

console

deployconf Force update the monitoring configuration file for theevent monitoring engine.

start

fence Alter workstation job fences in the production plan. fence

limit cpu Alter workstation job limits in the production plan. limit

link Open workstation links. link

resetfta Generates an updated Sinfonia file and sends it to afault-tolerant agent on which the Symphony file hascorrupted.

resetfta

showcpus Display workstations, domains and links in the plan. list

shutdown Shut down Tivoli Workload Scheduler processing. shutdown

start Start Tivoli Workload Scheduler processing. start

startappserver Start the application server. start

starteventprocessor Start the event processor server. start

startmon Start the event monitoring engine. start

stop Stop Tivoli Workload Scheduler processing. stop

stop;progressive Stop Tivoli Workload Scheduler processing progressively. stop

stopappserver Stop the application server. stop

stopeventprocessor Stop the event processor server. stop

stopmon Stop the event monitoring engine. stop

switcheventprocessor Switch the event processor server from the masterdomain manager to the backup master domain manageror vice versa.

start, stop

switchmgr Switch the domain manager functionality to aworkstation.

start, stop

unlink Close workstation links. unlink

Startup Start Tivoli Workload Scheduler processing. start


All activities For any user to perform any workload service assuranceactivities, the TWS_user must have the following accesskeywords:


Example: To allow a user to display, list, and print workstation, workstation class,and domain definitions, and link and unlink workstations, specify:cpu access=display,link,unlink


||||

|

Object type - event

The following table gives the access keywords required to work with events:

Table 28. Events - access keywords

Activity


Composer


Use an event in an event rule definition. use

Example: To allow a user to use an event in an event rule definition, specify:event access=use

Object type - file

The following table gives the access keywords required to work with files (validonly for the command line.

You must specify the file names to which the type of access applies.

Table 29. Files - access keywords

Activity


Delete objects from the database. delete

dumpsec Create a text file of the settings contained in the compiled security file. display

JnextPlan Generate the production plan. build

makesec Compile the security file from a text file of the settings. modify

optman ls List all global options. display

show Show the details of a global option. display

change Change the details of a global option. modify

planman deploy Manually deploy event rules. build

prodsked Work with the production plan. build

stageman Carry forward incompleted job streams, archive the old production plan, andinstall the new production plan.

build

Example 1: To allow a user to manage the Security file, specify:file access=display,modify

Example 2: To allow a user to run JnextPlan, specify:file access=build

Note: The user will also be able to run planman deploy, prodsked, and stageman.

Object type - job

The following table gives the additional access keywords required to work withjobs, other than those described in Table 24 on page 121:


Table 30. Jobs - additional access keywords

Activity


Composer


Use jobs in job streams.

Also, if a job is used as a recovery job in a job definition, the user must have "use"access to the definition of the job identified as the recovery job.

use

Conman


adddep Add dependencies to jobs in the production plan. Not validfor workstations in end-to-end environment.

adddep

altpri Alter the priority of jobs in the production plan. Not valid forworkstations in end-to-end environment.

altpri

cancel job Cancel jobs in the production plan. Not valid forworkstations in end-to-end environment.

cancel

confirm Confirm completion of jobs in the production plan. Not validfor workstations in end-to-end environment.

confirm

deldep job Delete dependencies from jobs in the production plan. Notvalid for workstations in end-to-end environment.

deldep

display Display jobs in the plan. display

kill Kill running jobs. kill

release job Release jobs from dependencies in the production plan. Notvalid for workstations in end-to-end environment.

release

reply Reply to job prompts in the production plan. reply

rerun Rerun jobs in the production plan. Not valid for workstationsin end-to-end environment.

rerun

showjobs Display information about jobs in the production plan. list


Table 30. Jobs - additional access keywords (continued)

Activity


Conman


submitdocommand

Submit commands as jobs or recovery jobs into theproduction plan.

If the submit also identifies a second job with the "ALIAS" or"RECOVERYJOB" arguments, the user must have "submit"access to that other job, as well

Not valid for workstations in end-to-end environment.

submit

submit file Submit files as jobs or recovery jobs into the production plan.



submit

submit job Submit jobs or recovery jobs into the production plan.



submit

Restricts the submission action to jobs defined in thedatabase. With this authorization level a user cannot submitad hoc jobs. Use this keyword to allow a user to submit onlyjobs defined in the database. Use the submit keyword toallow a user to submit both defined and ad hoc jobs.

Users granted only submitdb rights:

v Cannot run submit docommand and submit filesuccessfully

v Are displayed tasks related to ad hoc job submission onthe graphical user interfaces, but if they run them, arereturned error messages for lacking the submit access right.

submitdb

submit sched Submit job streams into the production plan. Not valid forworkstations in end-to-end environment.

submit


For critical jobs onwhich you run anyof the followingactions:v Display hot listv Display critical

pathv Display

incompletedpredecessors

v Displaycompletedpredecessors

The predecessors are listed regardless of the fact that thisauthorization might not be extended to them. However, ifyou want to run any further action on any of the listedpredecessors, this will require that you have the properauthorization.

list





Example 1: To allow a user to manage only job dependencies, specify:job access=adddep,deldep

Example 2: To allow a user to only manage critical jobs, specify:job access=list,altpri

Example 3: User administrator is granted add and modify rights for all jobdefinitions, and is therefore permitted to create and modify job definitions that runscripts or commands as needed, with no restriction:USER TWSADMINCPU=@+LOGON=administratorBEGINJOB CPU=@ ACCESS=ADD,MODIFY,DISPLAY,...[...]END

User sconnor is granted the same rights for jobs that match the conditionjcltype=scriptname, which means that he can create or modify only job definitionsthat run scripts and cannot change any of them into a job that runs a command:USER RESTRICTEDCPU=@+LOGON=sconnorBEGINJOB CPU=@+JCLTYPE=SCRIPTNAME ACCESS=ADD,MODIFY,DISPLAY,...[...]END

Example 4: User administrator is granted submit permission for all jobs, and istherefore permitted to submit jobs defined in the database and ad hoc, with norestriction:USER TWSADMINCPU=@+LOGON=administratorBEGINJOB CPU=@ ACCESS=ADD,ADDDEP,...,RERUN,SUBMIT,USE,LIST,UNLOCK[...]END

User jsmith is granted submitdb permission for all jobs, allowing her to submit alljobs defined in the database, but she is not permitted to run ad hoc jobsubmissions:USER RESTRICTEDCPU=@+LOGON=jsmithBEGINJOB CPU=@ ACCESS=ADD,ADDDEP,...,RERUN,SUBMITDB,USE,LIST,UNLOCK[...]END

Object type - parameter

The following table gives the access keywords required to work with parameters:

Note: Starting from version 8.5, the parameter keyword is reserved for parameterscreated and managed in a local parameter database with the parms utilitycommand. See the Tivoli Workload Scheduler: User's Guide and Reference fordetails on parms.


Table 31. Parameters - additional access keywords

Activity


parms Manage local parameter definitions. display

Example: To allow a user to perform all activities on parameters, specify:parameter access=@

Object type - prompt

The following table gives the additional access keywords required to work withprompts, other than those described in Table 24 on page 121:

Table 32. Prompts - additional access keywords

Activity


Composer


Use prompts when defining or submitting jobs and job streams use

Conman


adddep Use prompts when adding dependencies to jobs in theproduction plan. Not valid for workstations in end-to-endenvironment.

use

recall Display prompts waiting for a response. display

reply Reply to a job or job stream prompt. reply

showprompts Display information about prompts. list

submitdocommand

Use prompts when submitting commands as jobs into theproduction plan. Not valid for workstations in end-to-endenvironment.

use

submit file Use prompts when submitting files as jobs into theproduction plan. Not valid for workstations in end-to-endenvironment.

use

submit job Use prompts when submitting jobs into the production plan.Not valid for workstations in end-to-end environment.

use

submit sched Use prompts when submitting job streams into theproduction plan. Not valid for workstations in end-to-endenvironment.

use

Example: To allow a user to perform all activities on prompts except reply tothem, specify:prompt access=use,display,list


Object type - report

The following table gives the access keywords required to work with reports.

Table 33. Files- access keywords

Activity


Tivoli Dynamic Workload Console Display reports on Tivoli Dynamic Workload Console. display

Example: To allow a user to display reports on the Tivoli Dynamic WorkloadConsole, specify:report access=display

Object type - resource

The following table gives the additional access keywords required to work withresources, other than those described in Table 24 on page 121:

Table 34. Resources - additional access keywords

Activity


Composer


Use resources when defining or submitting jobs and job streams use

Conman


adddep Use resources when adding dependencies to jobs in theproduction plan. Not valid for workstations in end-to-endenvironment.

use

resource Change the number of units of a resource on a workstation. resource

showresources Display information about resources. list

submitdocommand

Use resources when submitting commands as jobs into theproduction plan. Not valid for workstations in end-to-endenvironment.

use

submit file Use resources when submitting files as jobs into theproduction plan. Not valid for workstations in end-to-endenvironment.

use

submit job Use resources when submitting jobs into the production plan.Not valid for workstations in end-to-end environment.

use

submit sched Use resources when submitting job streams into theproduction plan. Not valid for workstations in end-to-endenvironment.

use

Example: To allow a user to display information about resources and change theunits of a resource on a workstation, but not to use them in any other schedulingobjects or actions, specify:resource access=list,resource

Object type - schedule

The following table gives the additional access keywords required to work with jobstreams, other than those described in Table 24 on page 121:


Table 35. Job streams - additional access keywords

Activity


Conman


adddep Add dependencies to job streams in the production plan. Notvalid for workstations in end-to-end environment.

adddep

altpri Alter the priority of job streams in the production plan. Notvalid for workstations in end-to-end environment.

altpri

cancel sched Cancel job streams in the production plan. Not valid forworkstations in end-to-end environment.

cancel

deldep sched Delete dependencies from job streams in the production plan.Not valid for workstations in end-to-end environment.

deldep

display Display job streams in the plan. . display

limit sched Modify the limit for jobs concurrently running within a jobstream.

limit

release sched Release job streams from dependencies in the productionplan. Not valid for workstations in end-to-end environment.

release

reply Reply to job stream prompts in the production plan. reply

showschedules Display information about job streams in the production plan. list

submit sched Submit job streams into the production plan.

If the submit also identifies a second job stream with the"ALIAS" argument, the user must have "submit" access tothat other job stream, as well


submit




Example: To allow a user to perform all actions on a job stream except submit itand release it, specify:schedule access=adddep,altpri,cancel,deldep,display,limit,reply,list

Object type - userobj

The following table gives the additional access keywords required to work withusers, other than those described in Table 24 on page 121:

Table 36. Users - additional access keywords

Activity


Conman


altpass Alter user passwords in the plan. altpass

Example: To allow a user to list and modify user information, includingpasswords in the database, specify:userobj access=display,modify,altpass


Object type - vartable

The following table gives the access keywords for using variable tables and thevariables they contain (this includes the global variables)

Table 37. Variable tables - access keywords

Activity


Composer


add Add new variable table (vartable) definitions in the databasefrom a file of object definitions. Unlock access is needed touse the ;unlock attribute. To add individual variable entrieswithin a table, the table must have modify access.

add,modify,unlock

create Create a text file of variable table (vartable) definitions in thedatabase. Modify access is need to use the ;lock attribute.Create individual variable entries within the table.

display,modify

delete Delete variable table (vartable) definitions from the database.To delete individual variable entries within a table, the tablemust have modify access.

delete

display Display variable table (vartable) definitions in the database.Display individual variable entries within the table.

display

extract Extract a text file of variable table (vartable) definitions fromthe database. Extract individual variable entries within thetable.

display

list List variable table (vartable) definitions in the database. Listindividual variable entries within the table.

display

lock Lock variable table (vartable) definitions in the database. modify

modify Modify variable table (vartable) definitions in the database.Definitions are extracted into a file. After you have edited thefile the definitions are used to replace the existing ones. Tomodify individual variable entries within a table, the tablemust have modify access.

add,modify

new Create variable table (vartable) definitions in the databasefrom a template.

add,modify

print Print variable table (vartable) definitions in the database.Print individual variable entries within the table.

display

rename Rename variable table (vartable) definitions in the database.The user needs add access to the new object and delete anddisplay access to the old object.

add, delete,display

replace Replace variable table (vartable) definitions in the database.Unlock access is needed to use the ;unlock attribute.

add,modify,unlock

unlock Unlock variable table (vartable) definitions in the database.Unlocking a table unlocks all the variables contained therein.Unlocking a variable unlocks the entire table where it isdefined.

unlock

Use variable tables in run cycles, job streams, and workstations use

Example: To allow a user only to use variable tables when defining otherscheduling objects, specify:vartable access=use


The TWS_user - special security file considerationsThe TWS_user is a special user, and requires special consideration for the securityfile.

Required access for the TWS_user for workload service assuranceFor any user to perform Workload service Assurance activities, theTWS_user must have display, modify and list access keywords assigned forall job, schedule and cpu objects.

New TWS_user in migrated Security fileIf you change the TWS_user of your environment, for example, as youmight do when performing a parallel upgrade, and then you migrate theSecurity file (to preserve your settings) you must set up the new TWS_userin the Security file in advance, with all its required access rights, beforeattempting to start Tivoli Workload Scheduler.

Sample security fileThis section contains a sample security file divided into sections for each differentclass of user.

Note that the order of definitions is from most to least-specific. Because of theorder, TWS_users and root users are matched first, followed by users in the sysgroup, and then users in the mis group. All other users are matched with the lastdefinition, which is the least specific.

TWS_users and root users logged in on the master domainmanager

user mastersm cpu=$master + logon=TWS_user,root############################################################ Sample Security File############################################################ APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON THE# MASTER DOMAIN MANAGER.user mastersm cpu=$master + logon=TWS_user,rootbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job access=@schedule access=@resource access=@prompt access=@file access=@calendar access=@cpu access=@parameter name=@ ~ name=r@ access=@userobj cpu=@ + logon=@ access=@eventrule name=@ access=add,delete,display,modify,list,unlockaction provider=@ access=display,submit,use,listevent provider=@ access=usereport name=@ access=displayvartable name=a@,$default access=add,delete,display,modify,use,list,unlockend

This user definition applies to GUI and CLI access for TWS_users and root userslogged into a master domain manager. They are given unrestricted access to allobjects, except parameters that have names beginning with r. Access to the r


||||||||||||||||||||||||

parameters is given only to users in the mis group. They are the only ones whocan generate all kinds of plans and who can create, update, and delete event ruledefinitions.

All users have access to all variable tables beginning with "a" and to the defaulttable, irrespective of the default variable table name.

TWS_users and root users logged in on any domain manager(other than the master)

user testerlondon cpu=$manager + logon=TWS_user,root############################################################ Sample Security File############################################################ APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON ANY# DOMAIN MANAGER.user testerlondon cpu=$manager + logon=TWS_user,rootbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job access=add,delete,displayschedule access=add,delete,displayresource access=@prompt access=@file name=prodsked access=build, displayfile name=trialsked access=build, displaycalendar access=@cpu access=@parameter name=@ ~ name=v@ access=@userobj cpu=@ + logon=@ access=@eventrule name=@ access=add,delete,display,modify,list,unlockaction provider=@ access=display,submit,use,listevent provider=@ access=usereport name=@ access=displayvartable name=a@,$default access=add,delete,display,modify,use,list,unlockend

This user definition applies to GUI and CLI access for TWS_users and root userslogged into any domain manager other than the master. They are givenunrestricted access to all objects, except parameters that have names beginningwith v, and jobs and jobs streams to which they have limited access. They cangenerate all types of plans and can create, update, and delete event ruledefinitions.

All users have access to all variable tables beginning with "a" and to the defaulttable, irrespective of the default variable table name.

TWS_users and root users logged in on any workstation otherthan any domain manager

user sm logon=TWS_user,root############################################################ APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON ANY# WORKSTATION OTHER THAN THE MASTER DOMAIN MANAGER.user sm logon=TWS_user,rootbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job cpu=$thiscpu access=@schedule cpu=$thiscpu access=@resource cpu=$thiscpu access=@prompt access=@


|

|||||||||||||||||||||||||

||||||

||

calendar access=@cpu cpu=$thiscpu access=@parameter cpu=$thiscpu

~ name=r@ access=@action provider=@ access=display,submit,use,listevent provider=@ access=usereport name=RUNHIST,RUNSTATS access=displayfile name=globalopts access=displayend

This user definition applies to TWS_users and root users to whom definition (1)does not apply, which are those who are logged in on any workstation other thanthe master domain manager or any other domain manager. They are givenunrestricted access to all objects on their login workstation. Note that prompts,files, and calendars are global in nature and are not associated with a workstation.

They can use event rules, but are not allowed to create, update, or delete eventrule definitions.

Users logged into the sys group on the master domainmanager

user masterop cpu=$master + group=sys############################################################ APPLIES TO USERS LOGGED INTO THE SYS GROUP ON THE# MASTER DOMAIN MANAGER.user masterop cpu=$master + group=sysbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job cpu=@

+ logon="TWS_domain\\TWS_user" access=@job cpu=@

+ logon=root access=adddep,altpri,cancel,confirm,deldep,release,reply,rerun,submit,use

job cpu=@+ logon=$user,$jclowner~ logon=root access=add,adddep,altpri,

cancel,confirm,deldep,release,reply,rerun,submit,use

schedule cpu=$thiscpu access=@schedule cpu=@ access=adddep,altpri,cancel,

deldep,limit,release,submit

resource access=add,display,resource,use

file name=globalopts access=displayfile name=prodsked access=displayfile name=symphony access=displayfile name=trialsked access=build, displaycalendar access=display,usecpu access=@parameter name=@ ~ name=r@ access=@report name=RUNHIST,RUNSTATS access=displayend

This user definition applies to users logged into the sys group on the masterdomain manager. They are given a unique set of access capabilities. Multiple objectstatements are used to give these users specific types of access to different sets ofobjects. For example, there are three job statements:


||||||||||||||||||||||||||||||||||

v The first job statement permits unrestricted access to jobs that run on anyworkstation (@) under the user's name ($user).

v The second job statement permits specific types of access to jobs that run on anyworkstation and that run as root.

v The third job statement permits specific types of access to jobs that run on anyworkstation. The jobs must run under the user's name ($user) or under thename of the owner of the job file ($jclowner). Jobs that run as root are excluded.

They are the only users defined on the master domain manager, different frommaestro or root, who can generate trial and forecast plans.

Users logged into the sys group on any workstation otherthan the master domain manager

user op group=sys############################################################ APPLIES TO USERS LOGGED INTO THE SYS GROUP ON ANY# WORKSTATION OTHER THAN THE MASTER DOMAIN MANAGERuser op group=sysbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job cpu=$thiscpu

+ logon=$user access=@job cpu=$thiscpu

+ logon=root access=adddep,altpri,cancel,confirm,deldep,release,reply,rerun,submit,use

job cpu=$thiscpu~ logon=root access=adddep,altpri,cancel,

confirm,deldep,release,reply,rerun,submit,use

schedule cpu=$thiscpu access=@resource access=add,display,resource,useprompt access=add,display,reply,usecalendar access=usecpu cpu=$thiscpu access=console,fence,limit,

link,start,stop,unlinkparameter name=@ ~ name=r@ access=@end

###########################################################

This user definition applies to sys group users to whom definition (3) does notapply, which are those who are logged in on any workstation other than themaster domain manager. They are given a set of access capabilities similar to thosein definition (3). The exception is that access is restricted to objects on the user'slogin workstation ($thiscpu).

Users logged into the mis group on any workstationuser misusers group=mis############################################################ APPLIES TO USERS LOGGED INTO THE MIS GROUP ON# ANY WORKSTATION.user misusers group=misbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job cpu=$thiscpu



+ logon=$jclowner~ logon=root access=submit,use

schedule cpu=$thiscpu access=add,submit,modify,display

cpu type=agent,s-agent,ftaaccess=console,fence,limit,

link,start,stop,unlinkparameter name=r@ access=@parameter name=@ access=displayend###########################################################

This user definition applies to users logged into the mis group on any workstation.They are given a limited set of access capabilities to fault-tolerant, standard, anddynamic agents. Resources, prompts, files, calendars, and workstations are omitted,which prevents access to these objects. These users are given unrestricted access toparameters with names that begin with r, but can only display other parameters.

Users logged in to multiple groups [continue keyword]This is an example of a security file where the continue keyword is used. With thiskind of security file, users get all accesses defined for each group that they belongto. As a result, a user can get authorizations from multiple user definitions.############################################################ User misusers USER DEFINITION APPLIES TO USERS LOGGED IN TO# THE MIS GROUP ON ANY WORKSTATION.## User dbusers USER DEFINITION APPLIES TO USERS LOGGED IN TO# THE DB GROUP ON ANY WORKSTATION.## User default USER DEFINITION APPLIES TO ALL USERS.#

user misusers group=misbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job name=mis@ access=@schedule name=mis@ access=@parameter name=mis@ access=@continue

user dbusers group=dbbegin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job name=db_@ access=@schedule name=db_@ access=@parameter name=db_@ access=@continue

user default logon=@begin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------parameter name=@ access=displayend

###########################################################


|

|||

|||||||||||||||||||||||||||||||||||||

Users that belong only to the mis group get access to all objects that have a namestarting with the mis prefix, as specified in the user misusers user definition. Inaddition, the user default user definition gives them display access to allparameters.

Users that belong only to the db group get access to all objects that have a namestarting with the db_ prefix, as specified in the user dbusers user definition. Inaddition, the user default user definition gives them display access to allparameters.

Users that belong to both the mis and the db groups get access to the objects thathave a name starting with the mis prefix and to the objects that have a namestarting with the db_ prefix, as specified in the user misusers and in the userdbusers user definitions. In addition, the user default user definition gives themdisplay access to all parameters.

You must order definitions from most specific to least specific. The user defaultuser definition gives generic accesses, and must be therefore specified at the end ofthe file.

All other users logged in on any workstationuser default logon=@############################################################ APPLIES TO ALL OTHER USERS LOGGED IN ON ANY# WORKSTATION.user default logon=@begin# OBJECT ATTRIBUTES ACCESS CAPABILITIES# ---------- ------------ ----------------------job cpu=$thiscpu


+ logon=$jclowner~ logon=root access=submit,use

schedule cpu=$thiscpu access=add,submit,modify,display

cpu cpu=$thiscpu access=console,fence,limit,link,start,stop,unlink

parameter name=u@ access=@parameter name=@ ~ name=r@ access=displayend###########################################################

This user definition gives a set of default capabilities to users other than thosecovered by the preceding definitions (1 to 5). These users are given unrestrictedaccess to parameters with names that begin with u, but can only display otherparameters. No access is permitted to parameters with names that begin with r.


||||

||||

|||||

|||

Chapter 5. Configuring authentication

This section describes how to configure authentication using, amongst othermethods, the popular LDAP (Lightweight Directory Access Protocol). It is dividedinto these main topics:v “Where to configure authentication”v “Available configurations” on page 140v “How to configure authentication” on page 140v “Rules for using a Federated User Registry with Tivoli Workload Scheduler” on

page 141v “Configuring authentication using the Integrated Solutions Console” on page 142v “Configuring authentication using the WebSphere Application Server tools” on

page 143v “Completing the configuration” on page 154v “Example configurations of LDAP servers” on page 155v “Using the Pluggable Authentication Module” on page 157

Where to configure authenticationAuthentication must be configured on each instance of the embedded WebSphereApplication Server that you are installing, following these rules:

To authenticate command-line usersFor users of the command-line, the command-line client, the command-lineas clients connected to the master domain manager using HTTP or HTTPS,or of agents where the connector has been installed, the sameauthentication method must be configured for the following components:v Master domain managerv Backup master domain managerv Agents that have a connector installed

To authenticate Dynamic Workload ConsoleIf the Dynamic Workload Console is not installed on the same instance ofTivoli Workload Automation as the master domain manager, authenticationfor this instance must be separately configured. The authenticationconfiguration for one instance can be different from the other, unless youplan to use single sign-on, in which case it must be identical. If theDynamic Workload Console is installed in the same instance as the masterdomain manager, you do not need to separately configure authenticationfor it.

To authenticate z/OS connector usersIf the z/OS connector is not installed on the same instance of DynamicWorkload Console, authentication for this instance must be separatelyconfigured. The authentication configuration for one instance can bedifferent from the other, unless you plan to use single sign-on, in whichcase it must be identical. If the z/OS connector is installed in the sameinstance as the Dynamic Workload Console, you do not need to separatelyconfigure authentication for it.

To authenticate dynamic domain manager usersThe same authentication method must be configured for each dynamic


||||||||

domain manager and its corresponding backup dynamic domain manager.This authentication method does not need to be the same as that used forthe master domain manager.

Available configurationsOn installation, all Tivoli Workload Scheduler components that use the embeddedWebSphere Application Server are configured for authentication in VMM (VirtualMember Manager) mode. This creates a Federated User Registry, using which youcan choose to use one or more of the following authentication systems:v Local operating system - the default authentication system at installation on

Windows operating systemsv Custom (through PAM - Pluggable Authentication Module) - the default

authentication system at installation on UNIX and Linux operating systemsv LDAPv File Registry

If you want to use local OS as the authentication method for the DynamicWorkload Console on UNIX operating systems, perform the steps in “Configuringthe Dynamic Workload Console to use the local OS authentication method” onpage 83.

If you choose to enable LDAP, you can use one of the following servers, for whichsample configuration templates are supplied in this documentation:v IBM Tivoli Directory Serverv Sun Java Director Serverv Microsoft Windows Active Directoryv z/OS Integrated Security Services LDAP Server

How to configure authentication

LDAP can be configured in either of these ways:

Using the Integrated Solutions ConsoleOn each instance of the embedded WebSphere Application Server whereyou want to modify the default authentication configuration you open theIntegrated Solutions Console and select to configure Global Security. Youchoose and configure the authentication mechanism or mechanisms youuse in your environment.

See “Configuring authentication using the Integrated Solutions Console”on page 142 for a full description.

Manually, using the WebSphere Application Server tools supplied with theproduct

On each instance of the embedded WebSphere Application Server whereyou want to modify the default authentication configuration you run ascript called showSecurityProperties to create a template containing thecurrent security configuration. You modify this template by adding andamending the properties that define the authentication mechanism ormechanisms you use in your environment. Finally, you run a script calledchangeSecurityProperties to update the WebSphere Application Serversecurity configuration.


||||

|

See “Configuring authentication using the WebSphere Application Servertools” on page 143 for a full description.

A typical configuration scenario

In a complex environment, you might want to use the following scenario toconfigure your chosen authentication mechanism across your workload schedulingenvironment:1. Use the changeSecurityProperties script to configure the mechanism on one

instance of WebSphere Application Server, for example that installed with themaster domain manager.

2. Test that you can log in using the configured authentication with several userIDs.

3. On that instance run the showSecurityProperties script and save the output tocreate a text template file containing the configuration. showSecurityPropertiesextracts only those configurations that have been created by using thechangeSecurityProperties.

4. On each of these systems where you want to configure authenticationv Copy the text template file created in the previous step.v Run showSecurityProperties and save the output file.v Merge this output file with the configuration template file.v Run changeSecurityProperties to update the WebSphere Application Server

configuration.v Test that you can log in using the configured authentication with several user

IDs.

Rules for using a Federated User Registry with Tivoli WorkloadScheduler

This section describes the simple rules you must follow when configuring TivoliWorkload Scheduler to use a Federated User Registry:

No duplicate User IDsYou can define any number of user registries in a Federated User Registry.However, no user ID must be present in more than one registry (thisprohibits using both Local OS and PAM as a joint authenticationmechanism). Thus, if you configure multiple user registries it is becauseyou have users in different non-inclusive groups that use different userregistries and which need to access Tivoli Workload Scheduler.

Reserved registry IDsThe WebSphere Application Server tools use some specific IDs to recognizethe registries and these are thus reserved keywords that you cannot use tocreate your own registries, whichever method you use to configure them:

twaLocalOSIdentifies the custom user registry bridge adapter configured forlocal operating system users

twaPAMIdentifies the custom user registry bridge adapter configured to usethe Pluggable Authentication Module (PAM) with Tivoli WorkloadScheduler – it is not available on Windows operating systems

Chapter 5. Configuring authentication 141

|||

||||

twaLDAPIdentifies the user registry bridge configured for LDAP users

defaultWIMFileBasedRealmIdentifies the default embedded WebSphere Application Server FileRegistry

CompatibilityTo ensure compatibility with nodes in your Tivoli Workload Schedulernetwork that are at a previous version, only Tivoli Workload Schedulercomponents and Dynamic Workload Console at version 8.4 and higher canbe configured with an LDAP login.

Configuring authentication using the Integrated Solutions Console

The Integrated Solutions Console is installed automatically with every instance ofthe embedded WebSphere Application Server. Use it to configure authentication asfollows:1. Login to the Dynamic Workload Console

Login to the Dynamic Workload Console with the current WebSphereApplication Server administration credentials.

2. Backup the configuration

Backup the WebSphere Application Server configuration using the commandbackupConfig.

3. Access the Integrated Solutions Console

To access the Integrated Solutions Console, use one of the following URLs:https://<Hostname>:<adminSecurePort>/ibm/console/

http://<Hostname>:<adminPort>/ibm/console/

where:

HostnameThe fully qualified hostname or the IP address of the computer.

adminSecurePortIf you connect with HTTPS, supply the WebSphere Application ServerAdministration secure port, the default value of which is 31124.

adminPortIf you connect with HTTP, supply the WebSphere Application ServerAdministration port, the default value of which is 31123.

Examplehttps://mypc:31124/ibm/console/

4. Login to the console

Log into the console using the WebSphere Administration Server credentials.You supplied these when you installed the component on this system (theymight have been modified since then).

5. Navigate to the security section

Select Security � Global security

6. Configure your required authentication mechanism or mechanisms.

In the User account repository section you will see the default Federatedrepositories option selected. Click the adjacent Configure button. Use theIntegrated Solutions Console to configure your authentication mechanism or


mechanisms. When you modify the rows in the Repositories in the realmtable, the value InternalFileRepository corresponding to the RepositoryIdentifier column must not be deleted.For example, click Add Base entry to Realm ... to add a new repository, suchas LDAP.Use the built-in context-sensitive help to understand what information tosupply in each field.In addition, all the key/value pairs output by the showSecurityProperties toolare documented in “Security properties: reference” on page 144. Eachkey/value pair corresponds to a field or concept expressed in the GUI of theIntegrated Solutions Console; the keys are mnemonic, to help you make thecorrespondence.

7. Save the modified configuration

Click Save to save the new configuration.8. Restart the server

Stop the application server using the command stopappserver, as described inthe Tivoli Workload Scheduler: User's Guide and Reference. To stop the server, usethe original WebSphere administrator credentials.Restart the server using the command startappserver, as described in theTivoli Workload Scheduler: User's Guide and Reference.

Configuring authentication using the WebSphere Application Servertools

When you install a Tivoli Workload Scheduler component that uses the embeddedWebSphere Application Server, you also install a set of WebSphere ApplicationServer tools (sometimes called "wastools"). You use two of these tools to configurethe authentication for . For more general information about the tools, see“Application server utilities” on page 313.

You can use the application server tools to configure only the following LDAPservers:v Microsoft Active Directoryv Oracle Java System Directory Serverv IBM Tivoli Directory Server

For the other LDAP servers use the procedure described in “Configuringauthentication using the Integrated Solutions Console” on page 142.

To configure authentication, perform the following steps:1. Login to the Dynamic Workload Console with the current WebSphere

Application Server administration credentials.2. Backup the WebSphere Application Server configuration using the command

backupConfig.3. Dump your current security properties to a text file using the command

showSecurityProperties > <text_file>.4. Customize the security properties by editing <text_file>. See “Security

properties: reference” on page 144.5. Stop the server using the commands stopappserver, as described in the Tivoli

Workload Scheduler: User's Guide and Reference. To stop the server, use theoriginal WebSphere administrator credentials.


6. Load the new properties using the command changeSecurityProperties<text_file>.

7. Restart the server using the commands startappserver, as described in theTivoli Workload Scheduler: User's Guide and Reference.

Security properties: referenceThis section describes the important security properties in the file generated by theshowSecurityProperties script. It is divided into panels:

Global Security PanelRequired panel.################################################################Global Security Panel################################################################enabled=trueenforceJava2Security=falseuseDomainQualifiedUserNames=falsecacheTimeout=600ltpaTimeOut=720issuePermissionWarning=trueactiveProtocol=CSIuseFIPS=falseactiveAuthMechanism=SWAMactiveUserRegistry=LDAP LocalOS WIM Custom <repository_id>:<repository_base_name>#activeUserRegistry=Custom <is not available on Windows platforms>

Note to users of previous versions of Tivoli Workload Scheduler: Nearly all ofthe properties are unchanged with respect to previous Tivoli Workload Schedulerreleases.

The following property is new:

enabled=true|falseSpecifies if application security is enabled (true) or not (false). The defaultis "true".

enforceJava2Security=falseSpecify if Java 2 security is enabled (true). Tivoli Workload Scheduler doesnot support Java 2 security so this must be set to false (the default).

useDomainQualifiedUserNames=true|falseSpecify if domain-qualified (realm-qualified) user names are to be used(true). If this is set to true, all user names in the Security file must bequalified with their domains. The default is false. Changing this valuewhile using Tivoli Workload Scheduler could endanger your access to theproduct; if you need to do so discuss the best method with IBM SoftwareSupport.

cacheTimeout=<seconds>Specifies the timeout value in seconds for the security cache. The securitycache timeout can influence performance. The timeout setting specifieshow often to refresh the security-related caches. Security informationpertaining to beans, permissions, and credentials is cached. When the cachetimeout expires, all cached information becomes invalid. Subsequentrequests for the information result in a database lookup. Sometimes,acquiring the information requires invoking a Lightweight Directory AccessProtocol (LDAP)-bind or native authentication. Both invocations arerelatively costly operations for performance. Determine the best trade offfor the application, by looking at usage patterns and security needs for the


site. The default security cache timeout value is 600 seconds. If you have asmall number of users, it should be set higher than that, or if a largenumber of users, it should be set lower.

ltpaTimeout=<seconds>Specifies the cache timeout for the LTPA data. The LTPA timeout valueshould not be set lower than the security cache timeout. The default is 720seconds.

issuePermissionWarning=trueSpecifies that during application deployment and application start, thesecurity runtime issues a warning if applications are granted any custompermissions (true). Custom permissions are permissions that are defined bythe user applications, not Java API permissions. Java API permissions arepermissions in the java.* and javax.* packages. For Tivoli WorkloadScheduler leave the setting as "true".

activeProtocol=CSISpecifies the active authentication protocol for Remote Method Invocationover the Internet Inter-ORB Protocol (RMI IIOP) requests, when security isenabled. For Tivoli Workload Scheduler leave the setting as "CSI".

useFIPS=true|falseSpecify if the Tivoli Workload Scheduler network is FIPS compliant (true)and thus uses GSKit, for SSL or is not FIPS compliant (false), and usesOpenSSL. The default is false. See “FIPS compliance” on page 201 for moredetails.

activeAuthMechanism=SWAMSpecifies the active authentication mechanism. For Tivoli WorkloadScheduler leave the setting as "SWAM".

activeUserRegistry=<space_separated_list>Specifies a list of space-separated entries that identify the registries toenable. All the entries listed here will be enabled together in the VMMFederated User Registry. Allowed values are:v LocalOSv Custom (not available for Windows operating systems)v LDAPv WIMv <REPOSITORY_ID>:<REPOSITORY_REALM_BASENAME>

Use this if you have configured another repository using IntegratedSolutions Console or any other mechanism other than the TivoliWorkload Scheduler WebSphere Application Server tools, and you wantto enable such a repository either on its own or together with the defaultregistries indicated above.For example, if you have created a repository with id "BluePages" andwith a realm base name of "ibm.com®", you must specify:activeUserRegistry=BluePages:o=ibm.com <other_repository_ids>

Federated repository panelRequired panel.################################################################Federated Repository Panel################################################################PrimaryAdminId=UseRegistryServerId=ServerID=


ServerPassword=VMMRealm=TWSREALMVMMRealmDelimiter=@VMMIgnoreCase=true

Note to users of previous versions of Tivoli Workload Scheduler: This is a newpanel.

PrimaryAdminId=<name>Specifies the name of the user with administrative privileges which isdefined in the repository, for example, adminUser. The user name is used tolog on to the administrative console when administrative security isenabled. WebSphere Application Server requires an administrative userwhich is distinct from the server user identity so that administrativeactions can be audited.

UseRegistryServerId=true|falseSpecifies whether the server identity is to be generated automatically orsupplied manually.v If true, enables the application server to generate the server identity,

which is recommended for environments that contain only WebSphereApplication Server 6.1 or later nodes. Automatically generated serveridentities are not stored in a user repository.

v If false, requires that a user is specified as ServerID for internal processcommunication.

ServerID=<name>Specifies a user identity in the repository that is used for internal processcommunication. Configurations that also contain WebSphere ApplicationServer V6.0.x require a server user identity which is defined in the activeuser repository.

ServerPassword=<password>Specifies the password that corresponds to the ServerID.

VMMRealm=<name>Specifies the name of the realm. The default for this value is TWSREALM.Ensure this property is configured correctly for your environment, in orderto allow communication between different servers and to improve speed.

VMMRealmDelimiter=<value>Specifies the delimiter used to distinguish between user and realm whenfederating multiple repositories with different realms. The default value is"@".

VMMIgnoreCase=true|falseSpecifies whether a case-insensitive authorization check is performed.v If true, specifies that case sensitivity is not a consideration for

authorization. Must be set to true when enabling LDAP repository withIBM Tivoli Directory Server

v If false, the case of the user ID being authenticated will be used to matchagainst the user IDs in the registry.

LDAP PanelComplete this panel if configuring for an LDAP user registry.################################################################LDAP Panel################################################################LDAPServerType=IDSLDAPHostName=


LDAPPort=389LDAPBaseDN=LDAPBindDN=LDAPBindPassword=LDAPloginProperties=LDAPsearchTimeout=120LDAPsslEnabled=falseLDAPsslConfig=LDAPCertificateFilter=LDAPCertificateMapMode=EXACT_DN

Note to users of previous versions of Tivoli Workload Scheduler: This is not anew panel, but is significantly different from previous versions.

LDAPServerType=<name>Specifies the type of LDAP server to which you connect. If you use theIBM Tivoli Directory Server for z/OS, you must specify IDS . Allowedvalues are:

IDS IBM Tivoli Directory Server (the default LDAP value)

AD Microsoft Windows Active Directory

LDAPHostName=<IP_address_or_hostname>Specifies the host name of the primary LDAP server. This host name iseither an IP address or a domain name service (DNS) name.

LDAPPort=<number>Specifies the LDAP server port. The default value is 389, which is not aSecure Sockets Layer (SSL) connection. Use port 636 for an SSL connection.For some LDAP servers, you can specify a different port for a non-SSL orSSL connection.

LDAPBaseDN=<distinguished_name_list>Specifies the LDAP distinguished name (DN) of the base entry within therepository, which indicates the starting point for LDAP searches of thedirectory service. The entry and its descendants are mapped to the subtreethat is identified by the "twaLDAP" base entry. If this field is left blank,then the subtree defaults to the root of the LDAP repository.

For example, for a user with a DN of cn=John Doe , ou=Rochester, o=IBM,c=US, specify that the LDAPBaseDN has any of the following options:v ou=Rochester, o=IBM, c=US

v o=IBM c=US

v c=US

For authorization purposes, this field is case sensitive. This specificationimplies that if a token is received, for example, from another cell or Lotus®

Domino®, the base DN in the server must match the base DN from theother cell or Lotus Domino server exactly. If case sensitivity is not aconsideration for authorization, enable the Ignore case for authorizationoption.

LDAPBindDN=<name>Specifies the distinguished name (DN) for the application server to usewhen binding to the LDAP repository. If no name is specified, theapplication server binds anonymously. In most cases, LDAPBindDN andLDAPBindPassword are needed. However, when anonymous bind can satisfyall of the required functions, LDAPBindDN and LDAPBindPassword are notneeded.


|||

||

||

LDAPBindPassword=<password>Specifies the password for the application server to use when binding tothe LDAP repository.

LDAPloginProperties=<login_token_list>Specifies the login tokens to use to log into the application server. Thisfield takes multiple login tokens, delimited by a semicolon (;). For example,uid;mail. All login properties are searched during login. If multiple entriesor no entries are found, an error is given. For example, if you specify thelogin properties as uid;mail and the login ID as Bob, the search filtersearches for uid=Bob or mail=Bob. When the search returns a single entry,then authentication can proceed. Otherwise, an error is given.

If you supply more than one login token, the order you give to the logintokens is very important, because regardless of the token by which the useris authenticated, VMM sets the first property as the principal name. Thisprincipal name is then passed to Tivoli Workload Scheduler. For example,if you set the login properties to cn;mail, even if the user logs in with"mail", the principal name returned will be "cn"and the Tivoli WorkloadScheduler security checks (in the security file, for example) are performedusing the "cn" value for that user.

LDAPsearchTimeout=<value>Specifies the timeout value in milliseconds for an LDAP server to respondbefore the request is aborted. A value of 0 specifies that no search timelimit exists.

LDAPsslEnabled=true|falseSpecifies whether secure socket communication is enabled to the LDAPserver.v If true, SSL is enabled, and the Secure Sockets Layer (SSL) settings for

LDAP are used, if specified.v If false, SSL is not enabled.

LDAPsslConfig=<alias>Specifies the SSL configuration alias to use for LDAP outbound SSLcommunications. This option overrides the centrally managedconfiguration for the JNDI platform. The default value is"DefaultNode/DefaultSSLSettings".

LDAPCertificateFilter=<filter_specification>Specifies the filter certificate mapping property for the LDAP filter. Thefilter is used to map attributes in the client certificate to entries in theLDAP repository. If more than one LDAP entry matches the filterspecification at run time, authentication fails because the result is anambiguous match. The syntax or structure of this filter is:

<LDAP_attribute>=${<Client_certificate_attribute>}

For example, uid=${SubjectCN}.

The left side of the filter specification is an LDAP attribute thatdepends on the schema that your LDAP server is configured touse. The right side of the filter specification is one of the publicattributes in your client certificate. The right side must begin witha dollar sign ($) and open bracket ({) and end with a close bracket(}). You can use any of the following certificate attribute values onthe right side of the filter specification (the case of the strings isimportant):v ${UniqueKey}


v ${PublicKey}v ${PublicKey}v ${Issuer}v ${NotAfter}v ${NotBefore}v ${SerialNumber}v ${SigAlgName}v ${SigAlgOID}v ${SigAlgParams}v ${SubjectCN}v ${Version}

LDAPCertificateMapMode=<value>Specifies whether to map X.509 certificates into an LDAP directory byEXACT_DN or CERTIFICATE_FILTER.

Advanced LDAP PanelComplete this panel if configuring for an LDAP user registry.################################################################Advanced LDAP Panel################################################################LDAPUserEntityType=PersonAccountLDAPUserObjectClasses=LDAPUserSearchBases=LDAPUserSearchFilter=LDAPUserRDNAttributes=LDAPGroupEntityType=GroupLDAPGroupObjectClasses=LDAPGroupSearchBases=LDAPGroupSearchFilter=LDAPGroupSearchFilter=LDAPGroupRDNAttributes=LDAPOrgContainerEntityType=OrgContainerLLDAPOrgContainerObjectClasses=LDAPOrgContainerSearchBases=LDAPOrgContainerSearchFilter=LDAPOrgContainerRDNAttributes=LDAPGroupConfigName=ibm-allGroupsLDAPGroupConfigScope=allLDAPGroupConfigMemberNames=member;uniqueMemberLDAPGroupConfigMemberClasses=groupOfNames;groupOfUniqueNamesLDAPGroupConfigMemberScopes=direct;directLDAPGroupConfigMemberDummies=uid=dummy;

Note to users of previous versions of Tivoli Workload Scheduler: It is not a newpanel, but is different from previous versions.

LDAPUserEntityType=<value>Specifies the PersonAccount entity type name that is supported by themember repositories. By default, this value is "PersonAccount"

LDAPUserObjectClasses=<entity_type_list>Specifies the object classes that are mapped to the PersonAccount entitytype. You can specify multiple values delimited by a semicolon (;) LDAPentries that contain one or more of the object classes belong to this entitytype. You cannot map multiple entity types to the same LDAP object class.

LDAPUserSearchBases=<search_base_list>Specifies the search bases that are used to search the PersonAccount entitytype. The search bases specified must be subtrees of the base entry in therepository.


|||||||||||||||||||||||||

For example, you can specify the following search bases, where o=ibm,c=usis the base entry in the repository:v o=ibm,c=us

v cn=users,o=ibm,c=us

v ou=austin,o=ibm,c=us

In the preceding example, you cannot specify search bases c=us oro=ibm,c=uk.

Delimit multiple search bases with a semicolon (;). For example:ou=austin,o=ibm,c=us;ou=raleigh,o=ibm,c=us

LDAPUserSearchFilter=<name>Specifies the LDAP search filter that is used to search the PersonAccountentity type. If a search filter is not specified, the object classes and therelative distinguished name (RDN®) properties are used to generate thesearch filter.

LDAPUserRDNAttributes=<rdn_attributes_list>Specifies the relative distinguished name (RDN) properties that are used togenerate the search filter for the PersonAccount entity type. You can specifymultiple values delimited by a semicolon (;). Specify this value in the form<rdn_attribute_name>:<object_class>. object_class is optional; if you specify it,this value is used by the PersonAccount entity type to map thecorresponding rdn_attribute_name.

LDAPGroupEntityType=<name>Specifies the Group entity type name that is supported by the memberrepositories. By default, this value is Group.

LDAPGroupObjectClasses=<object_classes_list>Specifies the object classes that are mapped to the Group entity type. Youcan specify multiple values delimited by a semicolon (;) LDAP entries thatcontain one or more of the object classes belong to this entity type. Youcannot map multiple entity types to the same LDAP object class.

LDAPGroupSearchBases=<search_base_list>Specifies the search bases that are used to search the Group entity type.The search bases specified must be subtrees of the base entry in therepository. See "LDAPUserSearchBases" for more information.

LDAPGroupSearchFilter=<name>Specifies the LDAP search filter that is used to search the Group entitytype. If a search filter is not specified, the object classes and the relativedistinguished name (RDN) properties are used to generate the search filter.

LDAPGroupRDNAttributes=<rdn_attributes_list>Specifies the relative distinguished name (RDN) properties that are used togenerate the search filter for the Group entity type. You can specifymultiple values delimited by a semicolon (;). Specify this value in the form<rdn_attribute_name>:<object_class>. object_class is optional; if you specify it,this value is used by the Group entity type to map the correspondingrdn_attribute_name.

LDAPOrgContainerEntityType=<name>Specifies the OrgContainer entity type name that is supported by themember repositories. By default, this value is "OrgContainer".

LDAPOrgContainerObjectClasses=<object_classes_list>Specifies the object classes that are mapped to the OrgContainer entitytype. You can specify multiple values delimited by a semicolon (;) LDAP


entries that contain one or more of the object classes belong to this entitytype. You cannot map multiple entity types to the same LDAP object class.

LDAPOrgContainerSearchBases=<search_base_list>Specifies the search bases that are used to search the OrgContainer entitytype. The search bases specified must be subtrees of the base entry in therepository. See "LDAPUserSearchBases" for more information.

LDAPOrgContainerSearchFilter=<name>Specifies the LDAP search filter that is used to search the OrgContainerentity type. If a search filter is not specified, the object classes and therelative distinguished name (RDN) properties are used to generate thesearch filter.

LDAPOrgContainerRDNAttributes=<rdn_attributes_list>Specifies the relative distinguished name (RDN) properties that are used togenerate the search filter for the OrgContainer entity type. You can specifymultiple values delimited by a semicolon (;). Specify this value in the formrdn_attribute_name>:<object_class>. object_class is optional; if you specify it,this value is used by the OrgContainer entity type to map thecorresponding rdn_attribute_name.

LDAPGroupConfigName=<value>Specifies the name of the group membership attribute. Only onemembership attribute can be defined for each LDAP repository. EveryLDAP entry must have this attribute to indicate the groups to which thisentry belongs.

For example, memberOf is the name of the membership attribute that isused in Active Directory. Ibm-allGroups is the name of the membershipattribute that is used in IBM Tivoli Directory Server. The groupmembership attribute contains values that reference groups to which thisentry belongs. If User belongs to Group, then the value of the memberOfattribute of User must contain the distinguished name of Group. If yourLDAP server does not support the group membership attribute, then donot specify this attribute. The LDAP repository can look up groups bysearching the group member attributes, though the performance might beslower.

LDAPGroupConfigScope=<value>Specifies the scope of the group membership attribute. The default value isdirect. For IBM Tivoli Directory Server the value to specify is "all". ForActive Directory the value to specify is "direct" Allowed values:

direct The membership attribute contains direct groups only. Directgroups are the groups that contain the member.

For example, if Group1 contains Group2 and Group2 contains User1,then Group2 is a direct group of User1, but Group1 is not a directgroup of User1.

nested The membership attribute contains both direct groups and nestedgroups.

all The membership attribute contains direct groups, nested groups,and dynamic members.

LDAPGroupConfigMemberNames=<names_list>Specifies the names of the "member attributes" in LDAP. You can specifymore "member attributes" separating them with ";".


For example, member and uniqueMember are two commonly used names ofmember attributes. The member attribute is used to store the values thatreference members that the group contains. For example, a group typewith an object class groupOfNames has a member attribute named member;group type with object class groupOfUniqueNames has a member attributenamed uniqueMember.

An LDAP repository supports multiple group types if multiple memberattributes and their associated group object classes are specified.

LDAPGroupConfigMemberClasses=groupOfNames;groupOfUniqueNamesSpecifies the object class of the group that uses these member attributes. Ifthis field is not defined, this member attribute applies to all group objectclasses. You can specify more "member classes" separating them with ";".

If you specify more than one value in "LDAPGroupConfigMemberNames", thenyou can specify the class related to the specific member name defining theright value in the right position.

Example:LDAPGroupConfigMemberNames=member;uniqueMemberLDAPGroupConfigMemberClasses=groupOfNames;groupOfUniqueNames

LDAPGroupConfigMemberScopesSpecifies the scope of the members attribute. You can specify more"member scopes" separating them with ";". The default value is direct. Ifyou specify more than one value in "LDAPGroupConfigMemberNames", thenyou can specify the scope related to the specific member name defining theright value in the right position. Allowed values:

direct The member attribute contains direct members only. Directmembers are members that are directly contained by the group.For example, if Group1 contains Group2 and Group2 contains User1,then User1 is a direct member of Group2, but User1 is not a directmember of Group1.

nested The member attribute contains both direct members and nestedmembers.

all The member attribute contains direct members, nested members,and dynamic members.

Example:LDAPGroupConfigMemberNames=member;uniqueMemberLDAPGroupConfigMemberScopes=direct;all

LDAPGroupConfigMemberDummies=uid=dummy;Indicates that if you create a group without specifying a member a dummymember is filled in to avoid creating an exception about missing amandatory attribute. Allowed value is "uid=dummy" If you specify morethan one value in "LDAPGroupConfigMemberNames", then you canspecify the dummy member related to the specific member name definingthe right value in the right position.

Example:LDAPGroupConfigMemberNames=member;uniqueMemberLDAPGroupConfigMemberDummies=uid=dummy;

It means that only "member" have a "dummy member", while"uniqueMember" do not have a "dummy member" enabled.


SSL PanelThis panel is used to configure SSL and is not relevant to user authentication. Allproperties are unchanged with respect to the previous version.

J2C Authentication Data PanelThis panel is used to configure J2C Authentication and is not relevant to userauthentication. All properties are unchanged with respect to the previous version.

ChangeSecurityProperties - outputThe output of the ChangeSecurityProperties script contains messages that helpyou to understand if the configuration changes you have made have beenaccepted. These messages include those that are generated when upgrading aTivoli Workload Scheduler component or the Dynamic Workload Console from aversion prior to V8.6.

The sample output of the script is as follows:----------------------------------------------------------------------------------I: Using Property File: C:/TWS/wastools/FRESHI~1.TXT

I: Configuring Global Security ...I: The LTPA LTPA has been found.I: The LTPA timeout has been set to 720 minutesI: Setting the authentication mechanism to (cells/DefaultNode|security.xml#LTPA_1)I: Configuring SSL ...I: Configuring LocalOS registry ...I: twaLocalOS user registry bridge already existsI: Configuring Advanced J2C AuthI: twaLDAP LDAP user registry already existsI: Configuring LDAP ...I: Configuring Advanced LDAP ...I: Enabling "LocalOS" user registry bridgeI: Enabling "LDAP" user registry bridgeI: The Active Authentication Mechanism is (cells/DefaultNode|security.xml#LTPA_1)I: The Active User Registry is (cells/DefaultNode|security.xml#WIMUserRegistry_1)

with base entries:o=twaLocalOSo=twaLDAP

I: The VMM useRegistryServerId property is "true"I: The VMM ignoreCase property is "true"I: The VMM realm is "TWSREALM"I: Current LDAPServerType for user registry with id "twaLDAP" is "IDS"I: The activeAuthmechanism is LTPA

I: Validation success. Configuration saved----------------------------------------------------------------------------------

Each message begins with a letter indicating whether it is Informational (I), aWarning (W), or an Error (E).

Note:

1. In the event that an error occurs, the configuration is not changed.2. If a property is not supplied in the input file, the corresponding field in

the embedded WebSphere Application Server is not updated.3. If a password field is blank or “*****”, the corresponding password in the

embedded WebSphere Application Server is not updated.


Completing the configuration

After you have configured the WebSphere Application Server to use a newauthentication configuration, whichever configuration method you used, you mustalso perform the following steps:

1. Create users and groupsFollow these steps to create users and groups after you have configured the newuser registry (the example uses the Dynamic Workload Console but you canachieve the same result using composer..1. Login to the WebSphere Application Server using the newly changed

WebSphere Application Server administrative user and password.2. Assign the TWSWEBUIAdministrator role to the new administrative user.3. Create new users and groups and assign roles to them, as explained in

“Configuring roles to access the Dynamic Workload Console” on page 84.

2. Update the Tivoli Workload Scheduler security fileThe Tivoli Workload Scheduler security file needs to be updated to allow users toaccess Tivoli Workload Scheduler objects (see “Updating the security file” on page102 for full details). The following is a brief example of an updated security file,where the user TEST_LDAP has been added to the USER MAESTRO section:USER MAESTROCPU=@+LOGON=tws83,Administrator,administrator,TEST_LDAPBEGINUSEROBJ CPU=@ ACCESS=ADD,DELETE,DISPLAY,MODIFY,ALTPASS,UNLOCKJOB CPU=@ ACCESS=ADD,ADDDEP,ALTPRI,CANCEL,CONFIRM,DELDEP,DELETE,DISPLAY,KILL,

MODIFY,RELEASE,REPLY,RERUN,SUBMIT,USE,LIST,UNLOCKSCHEDULE CPU=@ ACCESS=ADD,ADDDEP,ALTPRI,CANCEL,DELDEP,DELETE,

DISPLAY,LIMIT,MODIFY,RELEASE,REPLY,SUBMIT,LIST,UNLOCKRESOURCE CPU=@ ACCESS=ADD,DELETE,DISPLAY,MODIFY,RESOURCE,USE,LIST,UNLOCKPROMPT ACCESS=ADD,DELETE,DISPLAY,MODIFY,REPLY,USE,LIST,UNLOCKFILE NAME=@ ACCESS=CLEAN,DELETE,DISPLAY,MODIFY,UNLOCKCPU CPU=@ ACCESS=ADD,CONSOLE,DELETE,DISPLAY,FENCE,LIMIT,LINK,MODIFY,

SHUTDOWN,START,STOP,UNLINK,LIST,UNLOCKPARAMETER CPU=@ ACCESS=ADD,DELETE,DISPLAY,MODIFY,UNLOCKCALENDAR ACCESS=ADD,DELETE,DISPLAY,MODIFY,USE,UNLOCKEND

In the example, note that the useDomainQualifiedUserNames security property is setto false, so the user name has been specified without its domain.

3. Update associated WebSphere Application Serverproperties

On both Windows and UNIX after the WebSphere Application Server has beenmodified to use LDAP, it is important to change the SOAP client properties andrevalidate the user credentials of the Windows services:

Update SOAP client properties

Use the updateWAS.sh/.bat script to update the SOAP client properties.(see “Application server - updating the SOAP properties after changing theWebSphere Application Server user or its password” on page 306 for fulldetails). For example:updateWas.sh -user [email protected] -password zzzz


where theuser and password options are the new logical user that isauthorized to stop the WebSphere Application Server. The user must bedefined in the user registry

Update Windows services

On Windows, after WebSphere Application Server has been modified touse LDAP, it is important to update or revalidate the credentials of theWindows services using the updateWasService.bat script (see “Applicationserver - updating the Windows services after modifications” on page 305for full details). For example:updateWasService -userid tws83 -password zzzz–wasuser TEST_LDAP –waspassword xxxxxx

where the –userid and –password options are the operating system user IDand password of the user that is running the WebSphere ApplicationServer process, and –wasuser and –waspassword are the new logical userthat is authorized to stop the WebSphere Application Server. The –wasusermust be defined in the user registry

4. Propagate the changesPropagate the changes you have made, as follows:1. Update the USERNAME and PASSWORD fields in the useropts file on every

command-line client that points to your workstation2. Update the USERNAME and PASSWORD fields in the useropts file on every

fault-tolerant agent in your environment that has an HTTP/HTTPS connectiondefined in localopts that points to your workstation. The HTTP/HTTPSconnection is used to submit a predefined job or jobstream.

3. Update the USERNAME and PASSWORD fields in the engine connectionparameters on every connected Dynamic Workload Console.

Note: To change the useropts file, change the USERNAME and type the newPASSWORD in plain text between quotes. The password will be encryptedthe first time you log in.

Example configurations of LDAP servers

Refer to this template also if you are using an IBM Tivoli Directory Server (ITDS)for z/OS LDAP server to access to information stored in RACF. Note that on theTivoli Integrated Portal, LDAP users are queried only by the userid attribute.Check that an auxiliary class of eperson type and an uid attribute is added to theLDAP user ID.

Active Directory################################################################Global Security Panel################################################################enabled=trueenforceJava2Security=falseuseDomainQualifiedUserNames=falsecacheTimeout=600ltpaTimeOut=720issuePermissionWarning=trueactiveProtocol=CSIuseFIPS=falseactiveAuthMechanism=LTPAactiveUserRegistry=WIM LocalOS LDAP


|||||

|

||||||||||||||

################################################################Federated Repository Panel################################################################PrimaryAdminId=tws_adminUseRegistryServerId=falseServerID=ServerPassword=VMMRealm=myrealmVMMRealmDelimiter=@VMMIgnoreCase=true

################################################################LDAP Panel################################################################LDAPServerType=ADLDAPHostName=myhostnameLDAPPort=389LDAPBaseDN=dc=test,dc=itLDAPBindDN=CN=ldap bind,DC=test,DC=itLDAPBindPassword=*****LDAPloginProperties=uidLDAPsearchTimeout=120000LDAPsslEnabled=falseLDAPsslConfig=LDAPCertificateFilter=LDAPCertificateMapMode=

################################################################Advanced LDAP Panel################################################################LDAPUserEntityType=PersonAccountLDAPUserObjectClasses=userLDAPUserSearchBases=LDAPUserSearchFilter=(objectCategory=user)LDAPUserRDNAttributes=sAMAccountName:userLDAPGroupEntityType=GroupLDAPGroupObjectClasses=groupLDAPGroupSearchBases=LDAPGroupSearchFilter=(objectCategory=group)LDAPGroupRDNAttributes=cn:groupLDAPOrgContainerEntityType=OrgContainerLDAPOrgContainerObjectClasses=organization;organizationalUnit;domain;containerLDAPOrgContainerSearchBases=LDAPOrgContainerSearchFilter=LDAPOrgContainerRDNAttributes=ou:organizationalUnit;cn:container;dc:domain;o:organization

LDAPGroupConfigName=memberOfLDAPGroupConfigScope=directLDAPGroupConfigMemberNames=memberLDAPGroupConfigMemberClasses=groupOfNamesLDAPGroupConfigMemberScopes=directLDAPGroupConfigMemberDummies=

IBM Tivoli Directory Server################################################################Global Security Panel################################################################enabled=trueenforceJava2Security=falseuseDomainQualifiedUserNames=falsecacheTimeout=600ltpaTimeOut=720issuePermissionWarning=trueactiveProtocol=CSIuseFIPS=false


||||||||||||||||||||||||||||||||||||||||||||||||||||||

|

|||||||||||

activeAuthMechanism=LTPAactiveUserRegistry= WIM LocalOS LDAP

################################################################Federated Repository Panel################################################################PrimaryAdminId=tws_adminUseRegistryServerId=falseServerID=ServerPassword=VMMRealm=myrealmVMMRealmDelimiter=@VMMIgnoreCase=true################################################################LDAP Panel################################################################LDAPServerType=IDSLDAPHostName=myhostnameLDAPPort=389LDAPBaseDN=o=ibm.comLDAPBindDN=LDAPBindPassword=LDAPloginProperties=mail;cnLDAPsearchTimeout=120000LDAPsslEnabled=falseLDAPsslConfig=LDAPCertificateFilter=LDAPCertificateMapMode=################################################################Advanced LDAP Panel################################################################LDAPUserEntityType=PersonAccountLDAPUserObjectClasses=user;ePersonLDAPUserSearchBases=LDAPUserSearchFilter=(objectclass=ePerson)LDAPUserRDNAttributes=mail:ePerson;cn:ePersonLDAPGroupEntityType=GroupLDAPGroupObjectClasses=group;groupOfUniqueNamesLDAPGroupSearchBases=LDAPGroupSearchFilter=(&(ou=memberlist)(ou=ibmgroups)(o=ibm.com)(objectclass=groupOfUniqueNames))LDAPGroupRDNAttributes=cn:groupOfUniqueNamesLDAPOrgContainerEntityType=OrgContainerLDAPOrgContainerObjectClasses=organization;organizationalUnit;domain;containerLDAPOrgContainerSearchBases=LDAPOrgContainerSearchFilter=LDAPOrgContainerRDNAttributes=ou:organizationalUnit;cn:container;dc:domain;o:organizationLDAPGroupConfigName=ibm-allGroupsLDAPGroupConfigScope=allLDAPGroupConfigMemberNames=uniqueMemberLDAPGroupConfigMemberClasses=groupOfUniqueNamesLDAPGroupConfigMemberScopes=directLDAPGroupConfigMemberDummies=

Using the Pluggable Authentication ModuleTivoli Workload Scheduler enhances the embedded WebSphere Application Serverby supporting a user authentication mechanism based on the PluggableAuthentication Module.

This enhancement provides a single authentication mechanism that is capable ofauthenticating users no matter what their user registry implementations are basedon, local OS or LDAP.


|||||||||||||||||||||||||||||||||||||||||||||||||||||||

|

Tivoli Workload Scheduler automatically installs the plug-in that enablesWebSphere Application Server to use Pluggable Authentication Module-enabledauthentication. The plug-in uses the service with name other. Ordinarily, you needdo nothing to configure the Pluggable Authentication Module. However, if thelevel of your authorizations inhibits you from using other, you should add theservice with name checkpassword in the /etc/pam.conf file.

The use of the Pluggable Authentication Module also extends the WebSphereApplication Server's capabilities to include support for authentication in HPTrusted Mode environments.

Tivoli Workload Scheduler is set by default to use a Pluggable AuthenticationModule user registry called "custom". If the Pluggable Authentication Module isnot configured with this registry, WebSphere Application Server looks in the localuser registry on the master domain manager.


Chapter 6. Network administration

This chapter describes how to administer the Tivoli Workload Scheduler network.It has the following topics:v “Network overview”v “Network definitions” on page 160v “Network communications” on page 160v “Network operation” on page 162v “Support for Internet Protocol version 6” on page 179v “Optimizing the network” on page 166v “Netman configuration file” on page 175v “Extended agents” on page 176v “IP address validation” on page 179v “Impact of network changes” on page 181

Network overviewA Tivoli Workload Scheduler network consists of one or more domains arrangedhierarchically. A Tivoli Workload Scheduler domain is a logical grouping ofworkstations, consisting of a domain manager and a number of agents.

D1

D2 D3

D4 D5 D6

D7 D8 D9 D10

DM

DM

FTA FTA

FTAFTA

SA

SA

XA

XA

D1 (Master Domain)

D2 - Dn

Subordinate D sM

Subordinate D sM

Parent DM

Figure 2. Tivoli Workload Scheduler network domain structure


Network definitionsDomain

A named group of Tivoli Workload Scheduler workstations consisting ofone or more agents and a domain manager. All domains have a parent,except the master domain.

Master domainThe topmost domain in an Tivoli Workload Scheduler network.

Master domain managerThe domain manager in the topmost domain of an Tivoli WorkloadScheduler network. It contains the centralized master files used todocument scheduling objects. It creates the Production Control file(Symphony) at the start of each production period and performs alllogging and reporting for the network. See also Domain Manager.

Backup master domain managerA fault-tolerant agent capable of assuming the responsibilities of the masterdomain manager.

Parent domainThe domain directly above the current domain. All domains, except themaster domain, have a parent domain. All communications to/from adomain is rooted through the parent domain manager.

Domain ManagerThe management hub in a domain. All communications in and from theagents in a domain is routed through the domain manager. See also MasterDomain Manager.

Backup domain managerA fault-tolerant agent capable of assuming the responsibilities of itsdomain manager.

Fault-tolerant agentAn agent workstation capable of resolving local dependencies andlaunching its jobs in the absence of a domain manager.

Standard agentAn agent workstation that launches jobs only under the direction of itsdomain manager.

Extended agentAn agent workstation that launches jobs only under the direction of itshost. Extended agents can be used to interface Tivoli Workload Schedulerwith non-Tivoli Workload Scheduler systems and applications

Host The scheduling function required by extended agents. It can be performedby any Tivoli Workload Scheduler workstation, except another extendedagent.

Network communicationsIn a Tivoli Workload Scheduler network, agents communicate with their domainmanagers, and domain managers communicate with their parent domainmanagers. There are basically two types of communications that take place:v Start-of-production period initialization (distribution of new Symphony file)v Scheduling events in the form of change-of-state messages during the production

period


Before the start of each new production period, the master domain manager createsa production control file called Symphony. Then, Tivoli Workload Scheduler isrestarted in the network, and the master domain manager sends a copy of the newSymphony file to each of its automatically-linked agents and subordinate domainmanagers. The domain managers, in turn, send copies to their automatically-linkedagents and subordinate domain managers. Agents and domain managers that arenot set up to link automatically are initialized with a copy of Symphony as soon as alink operation is run in Tivoli Workload Scheduler.

Once the network is started, scheduling messages, like job starts and completions,are passed from the agents to their domain managers, through parent domainmanagers to the master domain manager. The master domain manager thenbroadcasts the messages throughout the hierarchical tree to update the Symphonyfiles of all domain managers and the domain managers forward the messages to allfault-tolerant agents in their domain running in FullStatus mode.

Network linksLinks provide communications between Tivoli Workload Scheduler workstations ina network. Links are controlled by the AUTO Link flag, and the Console Managerlink and unlink commands. When a link is open, messages are passed betweentwo workstations. When a link is closed, the sending workstation stores messagesin a local pobox file and sends them to the destination workstation when the link isreopened.

This means that when links are closed, the message queues fill up with messagesfor the inaccessible workstations. To maximize the performance of Tivoli WorkloadScheduler, monitor workstations for closed links and attempt to reopen them assoon as possible.

Note: Extended agents do not have links. They communicate with their domainmanagers through their hosts.

To have a workstation link opened automatically, turn on the AUTO Link flag inthe workstation's definition. The link is first opened when Tivoli WorkloadScheduler is started on the Master Domain workstation. If the subdomain managerand workstations are not initialized and their AUTO Link flag is on, the masterdomain manager attempts to link to its subordinates and begin the initializationprocesses. If the AUTO Link flag is turned off, the workstation is only initializedby running a link command from the master domain manager. After theworkstation is initialized, it automatically starts and issues a link back to itsdomain manager.

If you stop a workstation, the links from it to other workstations are closed.However, the links from the other workstations to it remain open until either oneof the following situations occurs:v The stopped workstation is restarted and a link command is issuedv The other workstations' mailman processes time out, and perform an unlink for

the workstation

When the link command is issued and the connection has been established, if thedomain manager does not receive any reply within the timeout period, thechkhltst service is automatically invoked by mailman.

Chapter 6. Network administration 161

This service verifies that the workstation mailbox can be successfully read, andchecks if there are errors in the mailbox header. Resulting information is logged inthe TWSMERGE.log file of the domain manager as follows:v If a file system error occurs while opening the mailbox, the following message is

reported: AWSBDY126E An error occurred opening the Mailbox.msg file inCPU_NAME.

v If an error occurs while opening the mailbox because mailman is reading themailbox, the following message is reported: AWSBDY123I The Mailbox.msg filein CPU_NAME is correctly read by Mailman.

v If the mailbox is correctly opened, but an error occurs while reading the header,the following message is reported: AWSBDY125E An error occurred reading theheader of the Mailbox.msg file in CPU_NAME.

v If the mailbox is correctly opened and no error occurs while reading the header,the following message is reported: AWSBDY124W The Mailbox.msg file inCPU_NAME is not read by Mailman.

This service can also be launched manually by using the conman command. Seethe IBM Tivoli Workload Scheduler User's Guide and Reference for more details.

To be certain that inter-workstation communication is correctly restored, you canissue a link command after restarting a workstation.

Network operationThe batchman process on each domain manager and fault-tolerant agentworkstation operates autonomously, scanning its Symphony file to resolvedependencies and launch jobs. Batchman launches jobs via the jobman process. Ona standard agent, the jobman process responds to launch requests from the domainmanager's batchman.

The master domain manager is continuously informed of job launches andcompletions and is responsible for broadcasting the information to domainmanagers and fault-tolerant agents so they can resolve any inter-workstationdependencies.

The degree of synchronization among the Symphony files depends on the setting ofthe FullStatus mode in a workstation's definition. Assuming that these modes areturned on, a fault-tolerant agent's Symphony file contains the same information asthe master domain manager's (see the section that explains how to manageworkstations in the database in the Tivoli Workload Scheduler: User's Guide andReference).


Network processesNetman is started by the StartUp script (command). The order of process creationis netman, mailman, batchman, and jobman. On standard agent workstations,batchman does not run. All processes, except jobman, run as the TWS user.Jobman runs as root.

When network activity begins, netman receives requests from remote mailmanprocesses. Upon receiving a request, netman spawns a writer process and passesthe connection off to it. Writer receives the message and passes it to the localmailman. The writer processes (there might be more than one on a domainmanager) are started by link requests and are stopped by unlink requests (or whenthe communicating mailman terminates).

Domain managers, including the master domain manager, can communicate with alarge number of agents and subordinate domain managers. For improvedefficiency, you can define mailman servers on a domain manager to distribute thecommunications load (see the section that explains how to manage workstations inthe database in the Tivoli Workload Scheduler: User's Guide and Reference).

Symphony

BatchmanBatchman

Jobman Jobman

Job Job Job Job

Fault-tolerantagent

Master/domainmanager

Standardagent

Symphony

Jobman

Job Job

Figure 3. Symphony file synchronization


The StartUp command is normally run automatically, but can also be runmanually, as follows:

StartUp

Starts netman, the Tivoli Workload Scheduler network management process.

In Windows, the netman service is started automatically when a computer isrestarted. StartUp can be used to restart the service if it is stopped for any reason.

In UNIX, the StartUp command can be run automatically by invoking it from the/etc/inittab file, so that WebSphere Application Server infrastructure and netmanis started each time a computer is rebooted. StartUp can be used to restart netmanif it is stopped for any reason.

The remainder of the process tree can be restarted with theconman startconman startmon

commands. See the documentation about conman in the Tivoli Workload Scheduler:User's Guide and Reference for more information.

Note: If you start the StartUp command using a remote shell, the netman processmaintains the shell open without returning the prompt. To avoid thisproblem, modify the StartUp command so that the netman process is calledin the background, as follows:

Netman

Fault-tolerantagent

Master/domainmanager

StartUp

Writer

Mailman

Batchman

Jobman

Netman

StartUp

Writer

Mailman

Batchman

Jobman

Extendedagent

Non-Tivoli WorkloadScheduler system or

application

Method

Figure 4. Process creation on domain manager and fault-tolerant agent


# Start netman/usr/local/TWS851/mae851/TWS/bin/netman&

Authorization

You must have start access to the workstation.

Syntax

StartUp [–v | –u]

Arguments

–v Displays the command version and exits.

–u Displays command usage information and exits.

Examples

To display the command name and version, run the following command:StartUp -v

To start the netman process, run the following command:StartUp

Monitoring the Tivoli Workload Scheduler processesYou can use event-driven workload automation (EDWA) to monitor the status ofnetwork processes and to start a predefined set of actions when one or morespecific events take place. For more information about event-driven workloadautomation, refer to Tivoli Workload Scheduler: User's Guide and Reference.

You can monitor the following processes:v agentv appservmanv batchmanv jobmanv mailmanv monmanv netman

The .XML file contains the definition of a sample event rule to monitor the statusof the specified processes on the specified workstation. This event rule calls theMessageLogger action provider to write a message in a log file in an internalauditing database. If the condition described in the rule is already existing whenyou deploy the rule, the related event is not generated. For more information aboutthe MessageLogger action provider, refer to Tivoli Workload Scheduler: User's Guideand Reference:

<eventRule name="PROCESSES" ruleType="filter" isDraft="no"><eventCondition name="twsProcMonEvt1" eventProvider="TWSApplicationMonitor"eventType="TWSProcessMonitor">

<scope>AGENT, BATCHMAN DOWN</scope><filteringPredicate><attributeFilter name="ProcessName" operator="eq"><value>process_name1</value>

</attributeFilter>


<attributeFilter name="TWSPath" operator="eq"><value>TWS_path</value>

</attributeFilter><attributeFilter name="Workstation" operator="eq"><value>workstation_name</value>

</attributeFilter><attributeFilter name="SampleInterval" operator="eq"><value>sample_interval</value>

</attributeFilter>

</filteringPredicate></eventCondition><action actionProvider="MessageLogger" actionType="MSGLOG" responseType="onDetection"><scope>OBJECT=AAAAAAA MESSAGE=TWS PROCESS DOWN: %{TWSPROCMONEVT1.PROCESSNAME}

ON %{TWSPROCMONEVT1.TWSPATH}</scope><parameter name="ObjectKey"><value>object_key</value></parameter><parameter name="Severity"><value>message_severity</value>

</parameter><parameter name="Message"><value>log_message</value></parameter></action></eventRule>

</eventRuleSet>

where:

process_nameIs the name of the process to be monitored. You can insert more that oneprocess name, as follows:<attributeFilter name="ProcessName" operator="eq">

<value>agent</value><value>batchman</value></attributeFilter>

TWS_pathIs the directory containing the Symphony file and the bin directory.

workstation_nameIs the workstation on which the event is generated.

sample_intervalIs the interval, expressed in seconds, for monitoring the process status.

object_keyIs a key identifying the object to which the message pertains.

message_severityIs the severity of the message.

log_messageIs the message to be logged.

Optimizing the networkThe structure of a Tivoli Workload Scheduler network goes hand in hand with thestructure of your enterprise's network. The structure of the domains must reflectthe topology of the network in order to best use the available communicationchannels.


But when planning the Tivoli Workload Scheduler network, the following must betaken into consideration:v Data volumesv Connectivity

Data volumesNetwork capacity must be planned to adapt to the amount of data that iscirculating. Particularly high transmission volumes might be caused by thefollowing:v Transfer of large Symphony files.v Message traffic between the master domain manager and a FullStatus agent.v Message traffic from a domain manager when the domain has many agents.v Heavy use of internetwork dependencies, which extends traffic to the entire

network.

ConnectivityFor the more critical agents in your network, you need to consider their position inthe network. The reliability of workload execution on a particular agent dependson its capacity to receive a fresh Symphony file at the start of the productionperiod. If the workload contains many dependencies, a reliable connection to therest of the network is also required. These factors suggest that the best place forcritical agents is in the master domain, or to be set up as domain managersimmediately under the master domain manager, possibly receiving their Symphonyfiles through a set of dedicated mailman servers. Further, it is important for criticalagents that any domain manager above them in the tree structure must be hostedon powerful systems and must have an adequate backup system to ensurecontinuity of operation in the event of problems.

Tivoli Workload Scheduler provides two mechanisms to accommodate a particularnetwork situation: the domain structure and mailman servers. Whereas domainstructure establishes a hierarchy among Tivoli Workload Scheduler agents,mailman servers are used to tune the resources dedicated to the connectionbetween two agents.

DomainUse the Tivoli Workload Scheduler domain structure mechanism to create atree-shaped structure for the network, where all communications betweentwo points use the unique path defined by the tree (climb to the commonancestor and go down to the target, as opposed to direct TCPcommunication). As a consequence, the domain structure separates thenetwork into more-manageable pieces. This is for easier filtering, overview,action, and monitoring. However, it does also introduce some delay in theworkload processing. For instance when distributing the Symphony file, afault-tolerant agent inside a domain needs to wait for two steps ofSymphony distribution to be completed (from master domain manager todomain manager and from domain manager to fault-tolerant agent). Thesame is valid for every other type of communication that comes from themaster domain manager.

This has the following implications:v Critical business activities must be as close as possible to the master

domain managerv The domain manager must be installed on as powerful a workstation as

possible


v A similarly powerful backup domain manager must be included in thenetwork

v The network link between the domain manager and its backup must beas fast as possible to pass all the updates received from the subtree

v If intervention is needed directly on the domain, either give shell accessto the operators to use the Tivoli Workload Scheduler command line, orinstall a connector so that the Dynamic Workload Console can be used.

Mailman serversMailman servers allocate separate processes dedicated to thecommunication with other workstations. The main mailman is dedicated tothe transfer and network hub activities. The use of mailman servers on thedomain manager must be carefully planned. The main parameter is thenumber of downstream connections at each level of the tree. This numberdescribes the number of mailman servers that a main mailman isconnected to, or the number of agents a mailman server is connected to.The maximum number of downstream connections is about 20 for Solaris,50 for Windows and about 100 for other UNIX workstations, depending ontheir power. Typical downstream connections is about 10 for Solaris, about15 for Windows and about 20 for other UNIX workstations. However, youmust also take into consideration the link speed and the queue sizes,discussed below.

Planning space for queuesIn order to plan space for event queues, and possible alert levels and reactions, it isnecessary to model the flows passing through the agents, and the domainmanagers in particular.

For a typical domain manager, the main flow comes from update activity reportedby the sub tree, and from ad hoc submissions arriving from the master domainmanager and propagating to the entire network. Under these conditions, the mostcritical errors are listed by order of importance in Table 38 on page 169:

1

2

34

UpperDM

Update flow

Adhoc flow

Conman flow

DM

Full/status FTAs

FTA and domain sub-tree

Figure 5. Typical Tivoli Workload Scheduler network flows.


Table 38. Critical flow errors.

Flowno.

Location Queue Risk Impact

1 Upper domainmanager

dm.msg The queue fills up because of toomany unlinked workstations in thedomain or a downstream domainmanager has failed.

The upper domainmanager fails andpropagates the error.

2 Domain manager FullStatus fta.msg The queue fills because of too manyunlinked workstations in thedomain or because the FullStatusfault-tolerant agent is not copingwith the flow.

The domain manager failsand favors the occurrenceof #1.

3 Domain managerand FullStatusfault-tolerant agent

Mailbox.msg orIntercom.msg

The queue fills because theFullStatus fault-tolerant agent cannotcope with flow.

The FullStatusfault-tolerant agent failsand favors the occurrenceof #2.

4 Domain manager tomaster.msg The queue fills because of too manyunlinked workstations in thedomain.

The domain managerstarts to unlink the subtreeand accumulates messagesin the structure.

5 Fault-tolerant agentsonly whenenSwfaultTol globaloption is set to yes

deadletter.msg The queue fills because of too manyunlinked workstations in thedomain.

The agent stops.

6 Fault-tolerant agentsonly whenenSwfaultTol globaloption is set to yes

ftbox.msg This queue is circular. The rate ofmessages entering the queueexceeds the rate of messages beingprocessed, because of too manyunlinked workstations in thedomain.

Events are lost.

Note:

1. Flows are greater at the master domain manager and at any FullStatusfault-tolerant agents in the master domain than at subordinate domainmanagers or FullStatus fault-tolerant agents.

2. Use evtsize -show to monitor queue sizes.3. The amount of update flow is related to the amount of workload

running in a particular subtree and is unavoidable.4. The amount of ad hoc flow is related to the amount of additional

workload on any point of the network. It can be reduced by planningmore workload even if it is inactive. Note that simple reruns (not rerunfrom) do not create an ad hoc flow.

The planning, alert and recovery strategy must take into account the followingpoints:v Queue files are created with a fixed size and messages are added and removed

in a cyclical fashion. A queue reaches capacity when the flow of incomingmessages exceeds the outgoing flow for a sufficient length of time to use up theavailable space. For example, if messages are being added to a queue at a rate of1MB per time unit and are being processed and removed at a rate of 0.5 MB pertime unit, a queue sized at 10 MB (the default) is at capacity after 20 time units.But if the inward flow rate descends to be the same as the outward flow rateafter 19 time units, the queue does not reach capacity.


v The risk of the domain manager failing can be mitigated by switching to thebackup domain manager. In this case, the contents of the queues on the domainmanager are unavailable until the domain manager backup is started. In allcases, the size of the queue on the upper domain manager towards any otherdomain manager must respect condition A of Table 39.

v The risk that fault-switching fault-tolerant agents might not be able to cope withthe flow must be planned beforehand. The specifications for fault-switchingfault-tolerant agents must be similar to those of the domain manager, to avoidthat an agent receives a load that is not appropriate to its capacity. Check if aqueue is forming at the FullStatus fault-tolerant agents, both in ordinary andpeak operation situations.

v Once risk #2 has been dealt with, the possibility of a network link failure can bemitigated by sizing the queue from a domain manager to the FullStatusfault-tolerant agents appropriately as a function of the average network outageduration, and by increasing the size of the mailbox in case of unexpected longoutage (see condition B of Table 39).

v The same condition applies for avoiding an overflow of the domain manager'stomaster.msg queue with respect to network outages (see condition C) ofTable 39.

Table 39. Queue sizing conditions.

A MaxAlertTime <= size(UpperDM#queueToDM) / averageAdhocFlow

B MaxNetOutage <= size(DM#queueToFSFTA) / (averageAdhocFlow +averageUpdateFlow)

C MaxNetOutage <= size(DM#queueToUpperDM) / (averageUpdateFlow)

Monitoring the Tivoli Workload Scheduler message queuesYou can use event-driven workload automation (EDWA) to monitor the size ofmessage queues and to start a predefined set of actions when one or more specificevents take place. For more information about event-driven workload automation,refer to Tivoli Workload Scheduler: User's Guide and Reference.

You can monitor the following message queues:v appserverboxv mailboxv clboxv intercomv courierv monboxv moncmdv serverv tomasterv poboxv planbox

The following .XML file contains the definition of a sample event rule to monitorthe mailbox queue on the specified workstation and send an email when the fillingpercentage is greater than the specified value. If the condition described in the ruleis already existing when you deploy the rule, the related event is not generated.This event rule calls the MailSender action provider to send an email to the


|

receivers you specify. For more information about the MailSender action provider,refer to Tivoli Workload Scheduler: User's Guide and Reference:

<?xml version="1.0"?><eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules"xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/ruleshttp://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules/EventRules.xsd">

<eventRule name="MONITORQUEUE" ruleType="filter" isDraft="no"><eventCondition name="twsMesQueEvt1" eventProvider="TWSApplicationMonitor" eventType="TWSMessageQueues"><scope>MAILBOX FILLED UP 80% ON FTA</scope><filteringPredicate><attributeFilter name="MailboxName" operator="eq"><value>mailbox_name</value>

</attributeFilter><attributeFilter name="FillingPercentage" operator="ge"><value>filling_percentage</value></attributeFilter><attributeFilter name="Workstation" operator="eq"><value>workstation_name</value></attributeFilter><attributeFilter name="SampleInterval" operator="eq"><value>sample_interval</value>

</attributeFilter></filteringPredicate></eventCondition><action actionProvider="MailSender" actionType="SendMail" responseType="onDetection"><scope>TWSUSER@TWS : THE MAILBOX ON workstation_name...

</scope><parameter name="To"><value>main_receiver_list</value>

</parameter><parameter name="Subject"><value>mail_subject</value>

</parameter></action></eventRule></eventRuleSet>

where:

mailbox_nameIs the name of the mailbox to monitor.

filling_percentageIs the filling percentage. Supported operators are as follows:

ge causes the event generation when the mailbox filling percentageincreases over the threshold value. The event is generated only thefirst time the specified mailbox filling percentage is reached. If yourestart the SSM agent and the filling percentage is higher than thethreshold value, the event is generated again. Table 40 provides anexample in which the ge operator is set to 70%.

Table 40. Example for the ge operator

Mailbox name Filling percentage Action

Sample (0) >= 70% event not generated

Sample (0) < 70% event not generated

Sample (n-1) < 70% event not generated

Sample (n) >= 70% event generated


Table 40. Example for the ge operator (continued)


Sample (n+1) >= 70% event not generated

le causes the event generation when the mailbox filling percentagedecreases under the threshold value. The event is generated onlythe first time the specified mailbox filling percentage is reached. Ifyou restart the SSM agent and the filling percentage is lower thanthe threshold value, the event is not generated until the fillingpercentage increases over the threshold value and then decreasesunder it again. Table 41 provides an example in which the leoperator is set to 50%:

Table 41. Example for the le operator


Sample (0) <= 50% event not generated

Sample (0) > 50% event not generated

Sample (n-1) > 50% event not generated

Sample (n) <= 50% event generated

Sample (n+1) <= 50% event not generated


sample_intervalIs the interval, expressed in seconds, for monitoring the mailbox fillingpercentage.

main_receiver_listIs the main receiver list.

mail_subjectIs the subject of the mail.

Changing a queue sizeUse the evtsize command to resize a queue.

When you have used evtsize to resize a queue, the queue remain at that size untilthe next time you use evtsize. It only reverts to the default size of 10MB if youdelete it, at which point Tivoli Workload Scheduler recreates it with the defaultsize.

evtsize:

Defines the size of the Tivoli Workload Scheduler message files. This command isused by the Tivoli Workload Scheduler administrator either to increase the size of amessage file after receiving the message, “End of file on events file.”, or to monitorthe size of the queue of messages contained in the message file.

Authorization

You must be maestro or root in UNIX, or Administrator in Windows to runevtsize. Stop the IBM Tivoli Workload Scheduler engine before running thiscommand.


Syntax

evtsize -V | -U

evtsize file_name size

evtsize -compact file_name [size]

evtsize -show file_name

Arguments

-V Displays the command version and exits.

-U Displays command usage information and exits.

-compact file_name [size]Reduces the size of the specified message file to the size occupied by themessages present at the time you run the command. You can optionallyuse this keyword to also specify a new file size.

-show file_nameDisplays the size of the queue of messages contained in the message file

file_nameThe name of the event file. Specify one of the following:

Courier.msgIntercom.msgMailbox.msgPlanBox.msgServer.msgpobox/workstation.msg

size The maximum size of the event file in bytes. When first built by TivoliWorkload Scheduler, the maximum size is set to 10 MB.

Note: The size of the message file is equal to or bigger than the real size ofthe queue of messages it contains and it progressively increases untilthe queue of messages becomes empty; as this occurs the messagefile is emptied.

Examples

To set the maximum size of the Intercom.msg file to 20 MB, run the followingcommand:evtsize Intercom.msg 20000000

To set the maximum size of the pobox file for workstation chicago to 15 MB, runthe following command:evtsize pobox\chicago.msg 15000000

The following command:evtsize -show Intercom.msg

returns the following output:Tivoli Workload Scheduler (UNIX)/EVTSIZE 8.3 (1.2.2.4) Licensed Materials -Property of IBM(R)5698-WSH


||||||

(C) Copyright IBM Corp 1998, 2006 All rights reserved.US Government User Restricted RightsUse, duplication or disclosure restricted byGSA ADP Schedule Contract with IBM Corp.IBM is a registered trademark of International Business MachinesCorporation in the United States, other countries, or both.AWSDEK703I Queue size current 240, maximum 10000000 bytes (read 48, write 288)

where:880 Is the size of the current queue of the Intercom.msg file10000000

Is the maximum size of the Intercom.msg fileread 48

Is the pointer position to read recordswrite 928

Is the pointer position to write records

Tuning mailman serversOnce the distribution of agents to mailman servers has been established, all thegroups of agents attached to the same server must respect the link condition.

The link condition relates the number of agents connected to a mailman processand the tuning parameters for unlink on the mailman and writer side.

No_agents(i)The number of agents connected to a given mailman server i

Mm_unlinkA parameter set in the localopts of both domain manager and agent.Specifies the maximum number of seconds mailman waits before unlinkingfrom a workstation that is not responding.

Wr_unlinkA parameter set in the localopts of both domain manager and agent.Specifies the number of seconds the writer process waits before exiting ifno incoming messages are received.

Max_down_agentsThe maximum probable number of agents that are unavailable withouthaving the ignore flag set in the database and having the autolink flag on.

Avg_connect_timeoutThe system timeout (not set by Tivoli Workload Scheduler) for a TCPconnection. This can be computed by the command, which times outbecause no process is listening on that port.telnet agent inactive port

The condition is:

Wr_unlink = Mm_unlink > 1.2 * Max_down_agents * Avg_connect_timeout

This condition expresses that if the time before unlink is smaller than the probabletime of idle waiting of the mailman process (waiting connect timeout for eachagent that is currently down) in its loop to reactivate the connections, the agentsunlink constantly when some agents are down.


Netman configuration fileThe netman configuration file exists on all Tivoli Workload Scheduler workstationsto define the services provided by netman. It is called <TWA_home>/TWS/network/Netconf. The NetConf file includes comments describing each service. The servicesare:

2001 Start a writer process to handle incoming messages from a remotemailman.

2002 Start the mailman process. Mailman, in turn, starts the rest of the processtree (batchman, jobman).

2003 Stop the Tivoli Workload Scheduler process to handle incoming messagesfrom a remote mailman.

2004 Find and return a stdlist file to the requesting Conman process.

2005 Switch the domain manager in a domain.

2006 Locally download scripts scheduled by an Tivoli Workload Scheduler forz/OS master domain manager.

2007 Required to bypass a firewall.

2008 Stop Tivoli Workload Scheduler workstations in a hierarchical fashion

2009 Runs the switchmgr script to stop and restart a manager in such a waythat it does not open any links to other workstations until it receives theswitchmgr event. Can only be used when the enSwfaultTol global option isset to yes.

2010 Starts mailman with the parameter demgr. It is used by the service 2009.Can only be used when the enSwfaultTol global option is set to yes.

2011 Runs monman as a child process (son bin/monman.exe)

2012 Runs conman to stop the event monitoring engine (command bin/conman.exestopmon).

2013 Runs conman to switch event processors (command bin/conman.exeswitchevtproc -this)

2014 Runs conman to start event processing (command bin/conman.exestartevtproc -this)

2015 Runs conman to stop event processing (command bin/conman.exestopevtproc -this)

2016 Runs conman to force the update of the monitoring configuration file for theevent monitoring engine (command bin/conman.exe deployconf)

2017 Runs conman to stop event processing on a client (client bin/conman.exesynchronizedcmd -stopevtproc)

2018 Runs conman to check event processing on a client (client bin/conman.exesynchronizedcmd -checkevtproc)

2021 Runs conman to start appservman

2022 Runs conman to run the subcommand stopappserver that stops theapplication server

2023 Runs conman to run the subcommand startappserver that starts theapplication server

2501 Check the status of a remote job.


2502 Start the Console Manager – a service requested by the client side of theRemote Console. See the IBM Tivoli Remote Control: User's Guide for moreinformation.

2503 Used by the connector to interact with r3batch extended agent.

Determining internal Symphony table sizeThe mailman service (2002) can optionally take a parameter that determines theinitial size of the internal Symphony table. If you do not supply this parameter,mailman calculates the initial table size based on the number of records in the file.

Note: Mailman expands the table if it needs to, even if this parameter is notsupplied.

In normal circumstances, leave mailman to take the default value in the NetConffile as supplied (32000). However, if you are experiencing problems with memory,you can allocate a table that is initially smaller. To do this you change theparameter to the service 2002 in the NetConf file. The syntax for the entry is:

2002 son bin/mailman [ -parm <number> ]

where, <number> is used to calculate the initial Symphony table size based on thenumber of records in the Symphony file.

If r is the number of records in the Symphony file when batchman starts, Table 42shows how the size of the internal Symphony table is calculated, depending on thevalue of <number>:

Table 42. Calculation of internal Symphony table

Value of <number> Table size

0 (4/3r) + 512

nif n > r, nif n <= r, (4/3r) + 512

-1 65535

-nif +n => r, nif +n < r, r + 512

If during the production period you add more jobs, the maximum internalSymphony table size is increased dynamically, up to the maximum number ofrecords allowed in the Symphony file, which is 2,000,000,000.

Extended agentsAn extended agent is a logical workstation related to an access method hosted by aphysical Tivoli Workload Scheduler workstation (not another extended agent).More than one extended agent workstation can be hosted by the same TivoliWorkload Scheduler workstation and use the same access method. The extendedagent is defined using a standard Tivoli Workload Scheduler workstationdefinition, which gives the extended agent a name and identifies the accessmethod. The access method is a program that is run by the hosting workstationwhenever Tivoli Workload Scheduler submits a job to an external system.


Jobs are defined for an extended agent in the same manner as for other TivoliWorkload Scheduler workstations, except that job attributes are dictated by theexternal system or application.

Extended agent software is available for several systems and applications. TheUNIX extended agents, included with Tivoli Workload Scheduler, are described inthe following section. Please contact your sales representative for informationabout other extended agents. For information on defining Tivoli WorkloadScheduler workstations, see the section that explains how to manage workstationsin the database in the Tivoli Workload Scheduler: User's Guide and Reference. Forinformation on writing access methods, also see the Tivoli Workload Scheduler: User'sGuide and Reference.

UNIX extended agentsTivoli Workload Scheduler includes access methods for two types of UNIXextended agents. Use the Local UNIX method to enable a single UNIX workstationto operate as two Tivoli Workload Scheduler workstations, both of which can runTivoli Workload Scheduler scheduled jobs. Use the Remote UNIX access method todesignate a remote UNIX workstation to run Tivoli Workload Scheduler scheduledjobs without having Tivoli Workload Scheduler installed on it.

Information about a job's execution is sent to Tivoli Workload Scheduler from anextended agent using the job's stdlist file. A method options file can specifyalternate logins to launch jobs and check opens file dependencies. For moreinformation, see the Tivoli Workload Scheduler: User's Guide and Reference.

Local UNIX access methodThe Local UNIX method can be used to define multiple Tivoli Workload Schedulerworkstations on one workstation: the host workstation and one or more extendedagents. When Tivoli Workload Scheduler sends a job to a local UNIX extendedagent, the access method, unixlocl, is invoked by the host to run the job. Themethod starts by running the standard configuration script on the host workstation(<TWA_home>/TWS/jobmanrc). If the job's logon user is permitted to use a localconfiguration script and the script exists as $HOME/TWS/.jobmanrc, the localconfiguration script is also run. The job itself is then run either by the standard orthe local configuration script. If neither configuration script exists, the methodstarts the job.

The launching of the configuration scripts, jobmanrc and .jobmanrc is configurablein the method script. The method runs the configuration scripts by default, if theyexist. To disable this feature, you must comment out a set of lines in the methodscript. For more information, examine the script file <TWA_home>/TWS/methods/unixlocl on the extended agent's host.

Remote UNIX access methodThe Remote UNIX access method can be used to designate a non-Tivoli WorkloadScheduler workstation to run jobs scheduled by Tivoli Workload Scheduler. Youcan use unixrsh or unixssh:

The unixrsh methodWhen Tivoli Workload Scheduler sends a job to a remote UNIX extendedagent, the access method, unixrsh, creates a /tmp/maestro directory on thenon-Tivoli Workload Scheduler workstation. It then transfers a wrapperscript to the directory and runs it. The wrapper then runs the scheduledjob. The wrapper is created only once, unless it is deleted, moved, or isoutdated.


To run jobs using the extended agent, the job logon users must be givenappropriate access on the non-Tivoli Workload Scheduler UNIXworkstation. To do this, a .rhost, /etc/host.equiv, or equivalent file mustbe set up on the workstation. If opens file dependencies are to be checked,root access must also be permitted. Contact your system administrator forhelp. For more information about the access method, examine the scriptfile <TWA_home>/TWS/methods/unixrsh on an extended agent's host.

The unixssh methodThe unixssh method works like unixrsh but uses a secure remote shell toconnect to the remote host. The files used by this method are:methods/unixsshmethods/unixssh.wrp

The unixssh method uses the ssh keyword. You can generate this keywordwith any tools that are compatible with the secure remote shell.

Note: The passphrase must be blank.The following scenario gives an example of how to set up the method:

You have installed a Tivoli Workload Scheduler, version 8.4 fault-tolerantagent with the <TWS_user>: tws830. You want to run a remote shell in theremote host "REMOTE_HOST" with the user "guest". The procedure is asfollows:1. Create the public and private key for the user tws830, The following is

an example using rsa:a. Log on as tws830

b. Runssh-keygen -t rsa

c. When the tool asks for the passphrase, press Enter (leaving thepassphrase blank.) The keys are saved as follows:

Key Location Comment

Public <TWA_home>/TWS/.ssh/id_rsa.pub

Private <TWA_home>/TWS/.ssh/id_rsa Do not send this file!

Note: Different tools store the key in different places.2. At the remote host, do the following:

a. Telnet to the remote host.b. Log on as "guest".c. Change to the .ssh directory in the user's home directory, or create

it if it does not exist (the directory permissions must be adequate:for example, 600 for the directory and 700 for its contents.).

d. Append the public key you created in step 1. to the authorized_keysfile (create the file if it does not exist), using the command:cat id_rsa.pub >> authorized_keys

3. At the fault-tolerant agent, make the remote host "known" beforeattempting to let Tivoli Workload Scheduler processes use theconnection. This can be achieved in one of two ways:v Log on as tws830 and connect to the host using the command:

ssh -l guest <remote_host_name> ls


A prompt will be displayed saying that the host is not known, andasking permission to access it. Give permission, and the host will beadded to the list of known hosts.

v Alternatively, use the ssh documentation to add the remote host tothe file of known hosts.

Managing production for extended agentsIn general, jobs that run on extended agents behave like other Tivoli WorkloadScheduler jobs. Tivoli Workload Scheduler tracks a job's status and records outputin the job's stdlist files. These files are stored on the extended agent's hostworkstation. For more information on managing jobs, see the section that describesTivoli Workload Scheduler plan tasks in the Tivoli Workload Scheduler: User's Guideand Reference.

Failure launching jobs on an extended agentIf the access method is not located in the proper directory on the extended agent'shost, or the method cannot be accessed by Tivoli Workload Scheduler, jobs fail tolaunch or a file dependency is not checked. For a job, the Tivoli WorkloadScheduler job's logon or the logon specified in the method options file must haveread and execute permissions for the access method. When checking a file tosatisfy an opens dependency, root is used as the login unless another login isspecified in the method options file. For more information on method options, seethe Tivoli Workload Scheduler: User's Guide and Reference.

IP address validationWhen a TCP/IP connection is established, netman reads the requester's node nameand IP address from the socket. The IP address and node name are used to searchthe Symphony file for a known Tivoli Workload Scheduler workstation with one ofthe following possible results:v If an IP address match is found the validation is considered successful.v If a node name match is found, the validation is considered successful.v If no match is found in the Symphony file or the IP address returned does not

match the one read from the socket, the validation is considered unsuccessful.

The local option, nm ipvalidate, determines the action to be taken if IP validationis unsuccessful. If the option is set to full, unsuccessful validation causes TivoliWorkload Scheduler to close the connection and generate an error message. If theoption is set to none (default), Tivoli Workload Scheduler permits all connections,but generates a warning message for unsuccessful validation checks.

Support for Internet Protocol version 6Tivoli Workload Scheduler supports Internet Protocol version 6 (IPv6) in additionto the legacy IPv4. To assist customers in staging the transition from an IPv4environment to a complete IPv6 environment, Tivoli Workload Scheduler providesIP dual-stack support. In other terms, the product is designed to communicateusing both IPv4 and IPv6 protocols simultaneously with other applications usingIPv4 or IPv6.

To this end, the IPv4-specific gethostbyname and gethostbyaddr functions havebeen replaced by the new getaddrinfo API that makes the client-server mechanismentirely protocol independent.

The getaddrinfo function handles both name-to-address and service-to-porttranslation, and returns sockaddr structures instead of a list of addresses These


sockaddr structures can then be used by the socket functions directly. In this way,getaddrinfo hides all the protocol dependencies in the library function, which iswhere they belong. The application deals only with the socket address structuresthat are filled in by getaddrinfo.

Operating system configuration (UNIX only)IP validation depends on the system call getaddrinfo() to look up all the validaddresses for a host. The behavior of this routine varies, depending on the systemconfiguration. When getaddrinfo() uses the file /etc/hosts, it returns the firstmatching entry. If the connection is initiated on an address which appears after thefirst matching entry, IP validation fails. To resolve the problem, place the entryused to initiate the connection before any other matching entries in the /etc/hostsfile. If getaddrinfo() uses the "named" name server or the Network InformationService server and getaddrinfo() fails, contact your system administrator forassistance.

IP address validation messages

Following is a list of the messages for IP validation. If the Local Option nmipvalidate is set to none (default), the errors appear as warnings.

See the end of the list of conditions for the key to the variables:v Tivoli Workload Scheduler workstation name is not found in the Symphony file

Ip address validation failed for request:Service <num> for <program> on <workstation>(<operating_system_type>).Connection received from IP address:<c_ipaddr>. MAESTRO CPU <workstation> not found inSymphony file.

v Call to getaddrinfo() fails:

IP address validation failed for request:Service num for <program> on cpu(<operating_system_type>).Connection received from IP address:<c_ipaddr>. getaddrinfo() failed, unable toretrieve IP address of connecting node: <node>.

v IP Addresses returned by getaddrinfo() do not match the IP address ofconnection workstation:

IP address validation failed for request:Service <num> for <program> on <workstation>(<operating_system_type>).Connection received from IP address:<c_ipaddr>. System known IP addresses for nodename node: <k_ipaddr>.

v The IP address specified in the workstation definition for the Tivoli WorkloadScheduler workstation indicated in the service request packet does not match theIP address of connecting workstation:

IP address validation failed for request:Service <num> for <program> on <workstation>(<operating_system_type>).Connection received from IP address:<c_ipaddr>. TWS known IP addresses for cpu<k_ipaddr>.


v Regardless of the state of nm ipvalidate, the following information message isdisplayed when IP validation cannot be performed because the Symphony filedoes not exist or an error occurs when reading it:

IP address validation not performed forrequest: Service <num> for <program> on<workstation>(<operating_system_type>). Connection received from IPaddress: <c_ipaddr>. Cannot open or readSymphony file. Service request accepted.

Where:

<num>Service number (2001-writer, 2002-mailman...)

<program>Program requesting service

<workstation>Tivoli Workload Scheduler workstation name of connecting workstation

<operating_system_type>Operating system of connecting workstation

<node>Node name or IP address of connecting workstation

<c_ipaddr>IP address of connecting workstation

<k_ipaddr>Known IP address for connecting workstation

IP validation is always successful in the absence of a Symphony file. Incommunications from a domain manager to an agent it is normally successfulbecause a Symphony file does not yet exist. However, if the agent has a Symphony filefrom a previous run, the initial link request might fail if the Symphony file does notinclude the name of the domain manager.

Impact of network changesAny changes that you make to your network might have an impact on TivoliWorkload Scheduler. Workstations can be identified within Tivoli WorkloadScheduler by host name or IP address. Any changes to host names or IP addressesof specific workstations must obviously be also implemented in the TivoliWorkload Scheduler database. However, remember that if those workstations areinvolved in jobs that are currently scheduled in the Symphony file, those jobs arelooking for the old workstation identity.

Changes to host names or IP addresses of specific workstations can be activatedimmediately by running JnextPlan -for 0000. A new production plan is created(containing the updated IP addresses and host names), but the plan time span isnot extended.

Thus, plan any network changes with the job schedules in mind, and for majorchanges you are advised to suspend Tivoli Workload Scheduler activities until thechanges have been completed in the network and also implemented in the TivoliWorkload Scheduler database.


Network changes also have a specific impact on the connection parameters usedby the application server and the command line client:

Application serverIf you change the network you will need to change the communicationparameters specified in the application server's configuration files. How todo this is described in the appendix on the utilities supplied with theembedded WebSphere Application Server in the Tivoli Workload Scheduler:Planning and Installation Guide.

Command line clientWhen you connect from the command line client you supply a set ofconnection parameters. This is done in one of these ways:

From the localopts fileThe default method is that the connection parameters in thelocalopts file are customized when the command line client isinstalled.

From the useropts fileA useropts file might have been created for the user in question,containing a version of the connection parameters personalized forthe user.

In the command line, individuallyWhen you invoke one of the command line programs, you canoptionally include the parameters as arguments to the command.These override the values in the localopts or useropts files.

In the command line, in a fileWhen you invoke one of the command line programs, you canoptionally include the parameters in a file, the name of which isidentified as the -file argument to the command. These overridethe values in the localopts or useropts files.

Modify whichever method you are using to incorporate the new networkconnection details.


Chapter 7. Setting connection security

This chapter describes connection security. It is divided into the following sections:v “Connection security overview”v “Using SSL for netman and conman”v “Interface communication” on page 192v “Working across firewalls” on page 200v “FIPS compliance” on page 201

Connection security overviewTivoli Workload Scheduler uses the following protocols:v SSL for communication across the network by netman and conman

v HTTP/HTTPS over SSL for the command-line clientv RMI/IIOP over SSL for the Dynamic Workload Console

The Tivoli Workload Scheduler password encryption algorithm uses 3DES, whichis also known as Triple-DES, or DES-FDE3. The algorithm is run in Cipher BlockChaining Mode, which uses padding according to the PKCS#5 standard.

The product is installed with default settings that you customize according to yoursecurity requirements.

Before you perform any customization of the SSL connections, stop the WebSphereApplication server. Depending on the security settings you implement in yournetwork, you will need to reconfigure the security settings of the WebSphereApplication Server. This is described generically in “Changing the securitysettings” on page 296, and the detail of the procedure described therein is notrepeated in this chapter.

Using SSL for netman and conmanTivoli Workload Scheduler provides a secure, authenticated, and encryptedconnection mechanism for communication across the network topology. Thismechanism is based on the Secure Sockets Layer (SSL) protocol and uses theOpenSSL Toolkit, which is automatically installed with Tivoli Workload Scheduler.

The SSL protocol is based on a private and public key methodology. SSL providesthe following authentication methods:

CA trusting onlyTwo workstations trust each other if each receives from the other acertificate that is signed or is trusted. That is, if the CA certificate is in thelist of trusted CAs on each workstation. With this authentication level, aworkstation does not perform any additional checks on certificate content,such as the distinguished name. Any signed or trusted certificate can beused to establish an SSL session. See “Setting local options” on page 23 fora definition of the caonly option.

Check if the distinguished name matches a defined stringTwo workstations trust each other if, after receiving a trusted or signedcertificate, each performs a further check by extracting the distinguished


name from the certificate and comparing it with a string that was definedin its local options file. See “Setting local options” on page 23 for adefinition of the string option.

Check if the distinguished name matches the workstation nameTwo workstations trust each other if, after receiving a signed or trustedcertificate, each performs a further check by extracting the distinguishedname from the certificate and comparing it with the name of theworkstation that sent the certificate. See “Setting local options” on page 23for a definition of the cpu option.

To provide SSL security for a domain manager attached to z/OS in an end-to-endconnection, configure the OS/390® Cryptographic Services System SSL in the TivoliWorkload Scheduler code that runs in the OS/390 USS UNIX shell in the IBMTivoli Workload Scheduler for z/OS server address space. See the Tivoli WorkloadScheduler z/OS documentation.

When configuring SSL you can:

Use the same certificate for the entire networkIf the workstations are configured with CA trusting only, they acceptconnections with any other workstation that sends a signed or trustedcertificate. To enforce the authentication you define a name or a list ofnames that must match the contents of the certificate distinguished name(DN) field in the localopts file of each workstation.

Use a certificate for each domainInstall private keys and signed certificates for each domain in the network.Then, configure each workstation to accept a connection only with partnersthat have a particular string of the certificate DN field in the localopts fileof each workstation.

Use a certificate for each workstationInstall a different key and a signed certificate on each workstation and adda Trusted CA list containing the CA that signed the certificate. Then,configure each workstation to accept a connection only with partners thathave their workstation name specified in the Symphony file recorded in theDN field of the certificate.

Setting up private keys and certificates

To use SSL authentication on a workstation, you need to create and install thefollowing:v The private key and the corresponding certificate that identify the workstation in

an SSL session.v The list of certificate authorities that can be trusted by the workstation.

Use the openssl command line utility to:v Create a file containing pseudo random generated bytes (TWS.rnd). This file is

needed on some operating systems for SSL to function correctly.v Create a private key.v Save the password you used to create the key into a file.v Create a Certificate Signing Request.v Send this Certificate Signing Request (CSR) to a Certifying Authority (CA) for

signing, or:– Create your own Certificate Authority (CA)


– Create a self-signed CA Certificate (X.509 structure) with the RSA key of yourown CA

– Use your own Certificate Authority (CA) to sign and create real certificates

These actions will produce the following files that you will install on theworkstation(s):v A private key file (for example, TWS.key). This file should be protected, so that

it is not stolen to use the workstation's identity. You should save it in a directorythat allows read access to the TWS user of the workstation, such asTWA_home/TWS/ssl/TWS.key.

v The corresponding certificate file (for example, TWS.crt). You should save it in adirectory that allows read access to the TWS user of the workstation, such asTWA_home/TWS/ssl/TWS.crt.

v A file containing a pseudo-random generated sequence of bytes. You can save itin any directory that allows read access to the TWS user of the workstation, suchas TWA_home/TWS/ssl/TWS.rnd.

In addition, you should create the following:v A file containing the password used to encrypt the private key. You should save

it in a directory that allows read access to the TWS user of the workstation, suchas TWA_home/TWS/ssl/TWS.sth.

v The certificate chain file. It contains the concatenation of the PEM-encodedcertificates of certification authorities which form the certificate chain of theworkstation's certificate. This starts with the issuing CA certificate of theworkstation's certificate and can range up to the root CA certificate. Such a file issimply the concatenation of the various PEM-encoded CA certificate files,usually in certificate chain order.

v The trusted CAs file. It contains the trusted CA certificates to use duringauthentication. The CAs in this file are also used to build the list of acceptableclient CAs passed to the client when the server side of the connection requests aclient certificate. This file is simply the concatenation of the variousPEM-encoded CA certificate files, in order of preference.

Creating Your Own Certification Authority

If you are going to use SSL authentication within your company's boundaries andnot for outside internet commerce, you might find it simpler to create your owncertification authority (CA) to trust all your IBM Tivoli Workload Schedulerinstallations. To do so, follow the steps listed below.

Note: In the following steps, the names of the files created during the process TWSand TWSca are sample names. You can use your own names, but keep thesame file extensions.

1. Choose a workstation as your CA root installation.2. Type the following command from the SSL directory to initialize the pseudo

random number generator, otherwise subsequent commands might not work.v On UNIX:

$ openssl rand -out TWS.rnd -rand ./openssl 8192

v On Windows:$ openssl rand -out TWS.rnd -rand ./openssl.exe 8192

3. Type the following command to create the CA private key:$ openssl genrsa -out TWSca.key 1024

Chapter 7. Setting connection security 185

4. Type the following command to create a self-signed CA Certificate (X.509structure):$ openssl req -new -x509 -days 365 -key TWSca.key -out TWSca.crt -config ./

openssl.cnf

Now you have a certification authority that you can use to trust all of yourinstallations. If you wish, you can create more than one CA.

Creating private keys and certificates

The following steps explain how to create one key and one certificate. You candecide to use one key and certificate pair for the entire network, one for eachdomain, or one for each workstation. The steps below assume that you will becreating a key and certificate pair for each workstation and thus the name of theoutput files created during the process has been generalized to workstationname.

On each workstation, perform the following steps to create a private key and acertificate:1. Enter the following command from the SSL directory to initialize the pseudo

random number generator, otherwise subsequent commands might not work.v On Windows operating systems:

$ openssl rand -out workstationname.rnd -rand ./openssl.exe 8192

v On UNIX and Linux operating systems :$ openssl rand -out workstationname.rnd -rand ./openssl 8192

2. Enter the following command to create the private key (this example showstriple-DES encryption):$ openssl genrsa -des3 -out workstationname.key 1024

Then, save the password that was requested to encrypt the key in a file namedworkstationname.pwd.

Note: Verify that file workstationname.pwd contains just the characters in thepassword. For instance, if you specified the word maestro as thepassword, your workstationname.pwd file should not contain any CR orLF characters at the end (it should be 7 bytes long).

3. Enter the following command to save your password, encoding it in base64into the appropriate stash file:$ openssl base64 -in workstationname.pwd -out workstationname.sth

You can then delete file workstationname.pwd.4. Enter the following command to create a certificate signing request (CSR):

$ openssl req -new -key workstationname.key -out workstationname.csr-config ./openssl.cnf

Some values-such as company name, personal name, and more- will berequested at screen. For future compatibility, you might specify the workstationname as the distinguished name.

5. Send the workstationname.csr file to your CA in order to get the matchingcertificate for this private key.Using its private key (TWSca.key) and certificate (TWSca.crt), the CA will signthe CSR (workstationname.csr) and create a signed certificate (workstationname.crt)with the following command:$ openssl x509 -req -CA TWSca.crt -CAkey TWSca.key -days 365

-in workstationname.csr -out workstationname.crt -CAcreateserial


6. Distribute to the workstation the new certificate workstationname.crt and thepublic CA certificate TWSca.crt.

The table below summarizes which of the files created during the process have tobe set as values for the workstation's local options.

Table 43. Files for Local Options

Local option File

SSL key workstationname.key

SSL certificate workstationname.crt

SSL key pwd workstationname.sth

SSL ca certificate TWSca.crt

SSL random seed workstationname.rnd

Configuring SSL attributesUse the composer command line or the Dynamic Workload Console to update theworkstation definition in the database. See the Tivoli Workload Scheduler: User'sGuide and Reference for further information.

Configure the following attributes:secureaddr

Defines the port used to listen for incoming SSL connections. This valuemust match the one defined in the nm SSL port local option of theworkstation. It must be different from the nm port local option that definesthe port used for normal communications. If securitylevel is specified butthis attribute is missing, 31113 is used as the default value.

securitylevelSpecifies the type of SSL authentication for the workstation. It must haveone of the following values:enabled

The workstation uses SSL authentication only if its domainmanager workstation or another fault-tolerant agent below it in thedomain hierarchy requires it.

on The workstation uses SSL authentication when it connects with itsdomain manager. The domain manager uses SSL authenticationwhen it connects to its parent domain manager. The fault-tolerantagent refuses any incoming connection from its domain manager ifit is not an SSL connection.

force The workstation uses SSL authentication for all of its connectionsand accepts connections from both parent and subordinate domainmanagers. It will refuse any incoming connection if it is not an SSLconnection.

If this attribute is omitted, the workstation is not configured for SSLconnections. In this case, any value for secureaddr will be ignored. Youshould also set the nm ssl port local option to 0 to be sure that this port isnot opened by netman. The following table describes the type ofcommunication used for each type of securitylevel setting.


Table 44. Type of communication depending on the securitylevel value

Fault-tolerant agent (domainmanager)

Domain manager (parentdomain manager) Connection type

- - TCP/IP

Enabled - TCP/IP

On - No connection

Force - No connection

- On TCP/IP

Enabled On TCP/IP

On On SSL

Force On SSL

- Enabled TCP/IP

Enabled Enabled TCP/IP

On Enabled SSL

Force Enabled SSL

- Force No connection

Enabled Force SSL

On Force SSL

Force Force SSL

The following example shows a workstation definition that includes the securityattributes:cpuname MYWINos WNTnode apollotcpaddr 30112secureaddr 32222for maestroautolink offfullstatus onsecuritylevel onend

Configuring the SSL connection protocol for the network

To configure SSL for your network, perform the following steps:1. Create an SSL directory under the TWA_home/TWS directory. By default, the path

TWA_home/TWS/ssl is registered in the localopts file. If you create a directorywith a name different from ssl in the TWA_home/TWS directory, then update thelocalopts file accordingly.

2. Copy openssl.cnf and openssl.exe to the SSL directory3. Create as many private keys, certificates, and Trusted CA lists as you plan to

use in your network.4. For each workstation that will use SSL authentication:

v Update its definition in the Tivoli Workload Scheduler database with the SSLattributes.

v Add the SSL local options in the localopts file.


Although you are not required to follow a particular sequence, these tasks must allbe completed to activate SSL support.

In Tivoli Workload Scheduler, SSL support is available for the fault-tolerant agentsonly (including the master domain manager and the domain managers), but notfor the extended agents. If you want to use SSL authentication for a workstationthat runs an extended agent, you must specify this parameter in the definition ofthe host workstation of the extended agent.

Configuring full SSL securityThis section describes how to implement full SSL security when using an SSLconnection for communication across the network by netman and conman. Itcontains the following topics:v “Overview”v “Setting up full SSL security”v “Migrating a network to full SSL connection security” on page 190v “Configuring full SSL support for internetwork dependencies” on page 191

OverviewThis feature provides the option to set a higher degree of SSL-based connectionsecurity on Tivoli Workload Scheduler networks in addition to the alreadyavailable level of SSL security.

If you require a more complete degree of SSL protection, this enhancementsupplies new configuration options to setup advanced connection security.

If you do not require more SSL security than Tivoli Workload Scheduler hasprovided prior to the release of this feature, you can use the standard settingsdocumented above in this chapter.

The Full SSL security enhancements: Full SSL security support provides thefollowing enhancements:v TCP ports that can become security breaches are no longer left open.v Traveling data, including communication headers and trailers, is now totally

encrypted.

Compatibility between SSL support levels: The non-full and the full SSL supportlevels are mutually exclusive. That is, they cannot be configured simultaneouslyand cannot be enabled at the same time. If you enable full SSL support for a TivoliWorkload Scheduler network, any connection attempts by agents that are notconfigured for full SSL will be rejected by agents with full SSL support enabled.Vice versa, agents configured for full SSL support cannot communicate with therest of a network set up for non-full SSL support.

Setting up full SSL security

To set full SSL connection security for your network, you must, in addition to all thesteps described above in Chapter 7, “Setting connection security,” on page 183) configurethe following options:

enSSLFullConnection (or sf)Use optman on the master domain manager to set this global option to Yesto enable full SSL support for the network.


nm SSL full portEdit the localopts file on every agent of the network (including the masterdomain manager) to set this local option to the port number used to listenfor incoming SSL connections. Take note of the following:v This port number is to be defined also for the SECUREADDR parameter in

the workstation definition of the agent.v In a full SSL security setup, the nm SSL port local option is to be set to

zero.v You must stop netman (conman shut;wait) and restart it (StartUp) after

making the changes in localopts.v Check that the securitylevel parameter in the workstation definition of

each workstation using SSL is set at least to enabled.

Other than the changed value for secureaddr, no other changes are required in theworkstation definitions to set up this feature.

Migrating a network to full SSL connection security

Run the following steps to migrate your Tivoli Workload Scheduler version 8.3production environment to full SSL connection security support. The scenarioassumes that the network already runs on non-full SSL; that is, that the master andall the agents have:v The securitylevel attribute set to enabled, on, or force in their workstation

definition. On the master it is set to enabled.v Either the nm port or the nm SSL port local option configured and the port

number set as the value of the secureaddr attribute in their workstationdefinition.

v Group or individual private keys and certificates.

Proceed as follows:1. Upgrade all the agents. The objective is to upgrade locally every agent in the

network (including the master domain manager). You can perform this stepover several days. On the master and on every agent:a. Install the fix containing the full SSL support feature.b. Add the nm SSL full port local option and set it to a port number.At this stage, the network is still operating on non-full SSL connection security.

2. Enable full SSL support in the network. Perform this step in one single timeslot. To do this:a. Check that no firewall blocks the connection between the agents and their

domain manager (and, optionally, the master domain manager).b. In the workstation definition of the master and of every agent set the value

of the secureaddr attribute to the port number you configured for the nmSSL full port local option.

c. Use Optman to set the enSSLFullConnection global option to yes in thedatabase.

d. Run JnextPlan -for 0000 to make these settings operational.At this stage, the network is operating on full SSL connection security. Anyagents left on SSL security can no longer communicate with the rest of the fullSSL security network.The upgraded workstations still have the old SSL and TCP ports open inlistening mode. The aim of the final step is to close them down.


3. Disable the old SSL and TCP ports on the master and on every agent. You canperform this step over several days. To do this, edit the local options file ofevery workstation as follows:v On the workstations that have the securitylevel attribute set to enabled or

on, set the nm SSL port local option to 0.v On the workstations that have the securitylevel attribute set to force, set

both nm port and nm SSL port local options to 0.At this stage, all the agents operate with the new SSL connections and allagents set on securitylevel=force listen only on the new SSL full port. Fromnow on:v No bytes are sent in clear.v No active services are left in clear.v No TCP ports are left in listening mode on agents with securitylevel=force.

Configuring full SSL support for internetwork dependencies

The network agent that resolves internetwork dependencies requires a particularsetup for full SSL support.

To enable a network agent for full SSL support:1. Configure both the hosting and the remote fault-tolerant agents for full SSL

support.2. On the hosting fault-tolerant agent copy or move the netmth.opts file from the

TWA_home/TWS/config to the TWA_home/TWS/methods directories and add (andconfigure) the following options:

SSL remote CPUThe workstation name of the remote master or fault-tolerant agent.

SSL remote full portThe port number defined for full SSL support on the remote master orfault-tolerant agent.

The local options that specify the private key and certificate on the hostingfault-tolerant agent

These are documented in the “Setting local options” on page 23).Note that if the hosting fault-tolerant agent hosts more than one network agent,the TWA_home/TWS/methods directory contains one netmth.opts file for everydefined network agent. In this case the complete name of each netmth.opts filemust become:network-agent-name_netmth.opts

If the TWA_home/TWS/methods directory contains both network-agent-name_netmth.opts and netmth.opts files, only network-agent-name_netmth.optsis used. If multiple agents are defined and the directory contains onlynetmth.opts, this file is used for all the network agents.

The following example adds full SSL support to the example described in A samplenetwork agent definition in the Tivoli Workload Scheduler: User's Guide and Reference:v This is the workstation definition for the NETAGT network agent:

CPUNAME NETAGTDESCRIPTION "NETWORK AGENT"OS OTHERNODE MASTERA.ROME.TIVOLI.COMTCPADDR 31117


FOR maestroHOST MASTERBACCESS NETMTH

END

v These are the full SSL security options in the netmeth.opts file of NETAGT:####################################################### Remote cpu parameters######################################################

SSL remote full port = 31119SSL remote CPU = MASTERA

####################################################### Configuration Certificate######################################################

SSL key ="C:\TWS\installations\SSL\XA.key"SSL certificate ="C:\TWS\installations\SSL\XA.crt"SSL CA certificate ="C:\TWS\installations\SSL\VeriSte.crt"SSL key pwd ="C:\TWS\installations\SSL\XA.sth"SSL certificate chain ="C:\TWS\installations\SSL\TWSCertificateChain.crt"SSL random seed ="C:\TWS\installations\SSL\random_file.rnd"SSL auth mode =cpuSSL auth string =tws

Note: The SSL configuration certificate options must refer to the private key andcertificate defined on the hosting fault-tolerant agent.

v This is the workstation definition for MASTERA (the remote workstation):CPUNAME MASTERA

OS WNTNODE 9.168.68.55 TCPADDR 31117SECUREADDR 31119DOMAIN NTWKAFOR MAESTRO

TYPE MANAGERAUTOLINK ONBEHINDFIREWALL OFFSECURITYLEVEL enabledFULLSTATUS ONSERVER H

END

Interface communicationThis section describes how to configure SSL communication for the TivoliWorkload Scheduler interfaces. It has the following topics:v “Overview”v “Customizing the connector configuration files” on page 194v “Changing a server key” on page 195v “Customizing the SSL connection for the Dynamic Workload Console” on page

196v “Customizing the SSL connection to the master domain manager and dynamic

domain manager” on page 197v “Customizing the SSL connection for a command-line client” on page 199

OverviewThe following interfaces use SSL encryption and server authentication tocommunicate:


Dynamic Workload Console and SOAP internal communication on masterdomain manager

The Dynamic Workload Console and the SOAP internal communication onthe master domain manager use RMI/IIOP over SSL. They use both theserver and client security features of WebSphere Application Server toimplement it.

The command-line clientThe command-line client communicates using HTTP/HTTPS over SSL, anddoes not use WebSphere Application Server

The command lineThe command-line on the master domain manager communicates usingHTTP/HTTPS over SSL, and does not use WebSphere Application Server

The Tivoli Workload Scheduler interfaces, with the exception of the command-lineinterface, use default certificates that are installed into default keystores. To setSSL, you customize the defaults to the required security level. The defaultcertificates are not used for the Dynamic Workload Console client authentication,which is obtained using a user ID and password. The default password associatedwith each of the default keystores is default.

The SSL security paradigm implemented in the WebSphere Application Serverrequires two stores to be present on the clients and the server: a keystorecontaining the private key and a trust store containing the certificates of thetrusted counterparts.

Figure 6 shows the server and client keys, and to where they must be exported forthe Dynamic Workload Console:

The diagram shows the keys that must be extracted and distributed to enable SSLbetween the master domain manager and the Dynamic Workload Console, andwithin the components for the internal SOAP connection. Each arrow in thediagram includes the following activities performed using an appropriate keymanagement tool on each keystore:1. Create a self-signed certificate or import a third party certificate

Server keyServer trust

Client keyClient trust

Server keyServer trust

Client keyClient trust

Master domain manager or connector

TDWC

Figure 6. SSL server and client keys


2. Extract a new key3. Open the appropriate trust store4. Use the new key to add a signed certificate to the trust store

In addition to creating a new key, for some of these key and trust stores you canalso customize the name, location, and password of the store. Table 45 details thepossibilities:

Table 45. Changes allowed in Tivoli Workload Scheduler key and trust stores

File Name Path Password New key

TWS server key store U U U U

TWS server trust store U U U U

TWS client key store U

TWS client trust store U

TDWC client key store U

TDWC client trust store U

The following sections tell you how to customize the configuration files for the keyand trust stores (where you need to make changes), and how to create a new key.

Customizing the connector configuration files

To make any changes to the name, location, password of the Tivoli WorkloadScheduler server key or trust stores, you must modify the configuration files whichdescribe them. The configuration files are as follows:

Configuration files for server key filesThe name and location of the server key and trust stores are contained inthe security.xml file located in the TWA_home/eWAS/profiles/TIPProfile/config/cells/DefaultNode/ directory. Alternatively, use theshowSecurityProperties tool.

The default names and locations are: TWSServerKeyFile.jks andTWSServerTrustFile.jks, located in TWA_home/eWAS/profiles/TIPProfile/etc

The following is an example of the security.xml that contains thosesettings:<repertoire xmi:id="SSLConfig_1" alias="DefaultNode/DefaultSSLSettings">

<setting xmi:id="SecureSocketLayer_1"keyFileName="/opt/ibm/TWA0/eWAS/profiles/TIPProfile/etc/

TWSServerKeyFile.jks"keyFilePassword="{xor}Ozo5PiozKw==" keyFileFormat="JKS"trustFileName="/opt/ibm/TWA0/eWAS/profiles/TIPProfile/etc/

TWSServerTrustFile.jks"trustFilePassword="{xor}Ozo5PiozKw==" trustFileFormat="JKS"clientAuthentication="false" securityLevel="HIGH"enableCryptoHardwareSupport="false">

<cryptoHardware xmi:id="CryptoHardwareToken_1"tokenType="" libraryFile="" password="{xor}"/><properties xmi:id="Property_6" name="com.ibm.ssl.protocol" value="SSL"/><properties xmi:id="Property_7" name="com.ibm.ssl.contextProvider"

value="IBMJSSE2"/></setting></repertoire>


Client key files for all componentsThe client key files are described in the file:TWA_home/eWAS/profiles/TIPProfile/properties/ssl.client.props

The information in this file must not be modified. An example of it is asfollows:# KeyStore informationcom.ibm.ssl.keyStoreName=ClientDefaultKeyStorecom.ibm.ssl.keyStore=/opt/ibm/TWA0/eWAS/profiles/TIPProfile/etc/

TWSClientKeyFile.jkscom.ibm.ssl.keyStorePassword={xor}Ozo5PiozKw\=\=com.ibm.ssl.keyStoreType=JKScom.ibm.ssl.keyStoreProvider=IBMJCEcom.ibm.ssl.keyStoreFileBased=true

# TrustStore informationcom.ibm.ssl.trustStoreName=ClientDefaultTrustStorecom.ibm.ssl.trustStore=/opt/ibm/TWA0/eWAS/profiles/TIPProfile/etc/

TWSClientTrustFile.jkscom.ibm.ssl.trustStorePassword={xor}Ozo5PiozKw\=\=com.ibm.ssl.trustStoreType=JKScom.ibm.ssl.trustStoreProvider=IBMJCEcom.ibm.ssl.trustStoreFileBased=true

To modify the server key file names, paths, or passwords, modify the configurationfiles using the script changeSecurityProperties located in theTWA_home/TWS/wastool directory. For instructions on how to do this see “Changingthe security settings” on page 296. The following is a sample of the input:################################################################SSL Panel################################################################alias=DefaultSSLSettingskeyFileName=${USER_INSTALL_ROOT}/etc/TWSServerKeyFile.jkskeyFilePassword=*****keyFileFormat=JKStrustFileName=${USER_INSTALL_ROOT}/etc/TWSServerTrustFile.jkstrustFilePassword=*****trustFileFormat=JKSclientAuthentication=falsesecurityLevel=HIGHenableCryptoHardwareSupport=false

Changing a server key

You change a server key when you want the console or command-line client tosafely authenticate with their server. Changing a connector private key means thatthe trusted server certificates for the consoles and command-line client must alsobe updated.

This section describes how to apply changes to the connector side.

“Customizing the SSL connection for a command-line client” on page 199 describesthe configuration for the command-line client.

“Customizing the SSL connection for the Dynamic Workload Console” on page 196describes the configuration for the Dynamic Workload Console.

You can customize certificates and update server keystores using ikeyman that isprovided with the embedded WebSphere Application Server, or using the keytoolutility provided with the Java runtime environment. There are also other tools


distributed with other products or available in the Internet. For the connectorikeyman is located in the directory TWA_home/eWAS/bin. The keytool utility islocated in TWA_home/eWAS/java/jre/bin.

You can change the server key with a new self signed certificate that you generatedirectly, or with a certificate signed by a Certificate Authority.

If you use a self signed certificate for the server, replace the server private key inthe server Key keystore and the server public key in the Trust keystores for all theconsoles and command-line clients that connect to it.

If you use a certificate signed by a Certificate Authority, replace the server privatekey in the server Key keystore and make sure you have the certificate of theCertificate Authority in the Trust keystores for all the consoles and command-lineclients that connect to it.

The following procedure is an example of how to create a new server key pairusing the keytool utility:1. Generate an RSA key pair for the connector in the keystore:

keytool -genkey-alias tws-dname "CN=TWS, OU=Test, O=IBM, C=US"-keystore TWSServerKeyFile.jks-storepass default-keypass default-validity 3000-keyalg RSA

2. Export the certificate to PEM format and import it into the keystore:keytool -export

-alias tws-rfc-file server.crt-keystore TWSServerKeyFile.jks-storepass default

When creating self signed certificates, do not use the DSA algorithm as the TivoliWorkload Scheduler command-line utilities cannot use it to establish SSLconnection to the server. Make sure that the keys have the same password as thekeystore where they are contained. Make sure you update the Trust keystores forthe consoles and command-line client.

Customizing the SSL connection for the Dynamic WorkloadConsole

When you change the connector private key you need to update the Trust keystoreof the Dynamic Workload Console with the public key pair when you use selfsigned certificates, or make sure that it contains the certificate of the CertificateAuthority.

When you configure the Dynamic Workload Console to connect to differentconnectors it must have a certificate in its Trust keystore that enables trust for eachconnector.


You can customize certificates and update the Dynamic Workload Console Trustkeystore using ikeyman that is provided with the embedded WebSphereApplication Server, or using the keytool utility provided with the Java runtimeenvironment.

For the Dynamic Workload Console ikeyman and the keytool utility are located inthe directory TWA_home/eWAS/profiles/TIPProfile/etc.

The following is an example of how to import the connector certificate in PEMformat:keytool -import

-alias tws-file server.crt-trustcacerts-noprompt-keystore TDWCClientTrustFile.jks-storepass default

When you are customizing the Dynamic Workload Console settings, make sure thekeys have the same password as the keystore where they are contained. Thekeystore password must correspond between the connector server and theDynamic Workload Console client. The keys in the Dynamic Workload ConsoleTrust and Key keystores must be paired with the keys in the connector Key andTrust keystores respectively.

Encrypt the password using the encryptProfileProperties utility. See “Applicationserver - encrypting the profile properties files” on page 305 for details on how toencrypt profile properties.

Customizing the SSL connection to the master domainmanager and dynamic domain manager

The connection to the broker server installed with the dynamic domain managerrequires the use of certificates from a certificate authority to provide authentication.In addition, the master domain managers, backup master domain managers, andz/OS controllers that communicate with the dynamic domain manager must bedefined on the related broker server to ensure role-based authorization.

The examples in this section refer to a dynamic domain manager, but the sameconfiguration applies to all the following components:v Master domain managerv Backup master domain manager (if any)v z/OS controller (if any)

When you install Tivoli Workload Scheduler, the default certificates providedensure correct authentication and role-based authorization between the masterdomain manager and the dynamic domain manager. The certificates installed withthe dynamic agents also ensure that they can connect to the dynamic domainmanager they are registered to and can perform operations that belong specificallyto the dynamic agents (role-based authorization). The default value for thecertificate is Server on the master domain manager and Client on the dynamicagents.

To ensure that the master domain manager can communicate with the dynamicdomain manager, the prefix of the common name of the master domain manager


|

|

|||||

||

|

|

|

||||||||

||

must be defined in the BrokerWorkstation.properties file located intheTWA_home/TDWB/config directory on the dynamic domain manager. This ensuresthat the dynamic domain manager recognizes the master domain manager as suchand allows it to perform operations that belong specifically to a master domainmanager (role-based authorization).

If you plan to use your own certificates rather than the default ones, ensure thatthe prefix of the common names present in the certificates on the master domainmanager is listed in the Broker.AuthorizedCNs option in theBrokerWorkstation.properties file on the dynamic domain manager.

If you modify the certificate on the master domain manager, add the prefix for thecommon name defined in the updated certificate also in the Broker.AuthorizedCNsoption in the BrokerWorkstation.properties file on the dynamic domain manager.

To modify the security settings, perform the following steps:1. Modify the certificate on the master domain manager. For example, define the

mdm1 common name in the certificate.2. Deploy the certificate to the master domain manager, as described in Chapter 7,

“Setting connection security,” on page 183.3. Modify the list of common names on the dynamic domain manager, as follows:

a. Browse to TWA_home/TDWB/config.b. Open file BrokerWorkstation.properties.c. In the option Broker.AuthorizedCNs, define one or more prefixes of common

names for the authorized master domain manager. Separate each value witha semicolon. For example, you can define the following list:Broker.AuthorizedCNs=mdm;mdm1;mdm2

This ensures that all master domain managers, if any, with a common nameequal to or starting with mdm can connect to the dynamic domain manager.

4. Stop and start the dynamic domain manager to make the change effective, asfollows:a. Use wastool stopBrokerApplication.sh on UNIX and Linux or

stopBrokerApplication.bat on Windows:stopBrokerApplication -user username -password password [-port portnumber]

where username and password are the credentials used at installation. Theparameter portnumber is optional. If it is not specified, the default is used.

b. Use wastool startBrokerApplication.sh on UNIX and Linux orstartBrokerApplication.bat on Windows:startBrokerApplication -user username -password password [-port portnumber]


For more information, see “BrokerWorkstation.properties file” on page 56 and“Starting, stopping, and displaying dynamic workload broker status” on page 298.


|||||

||||

|||

|

||

||

|

|

|

|||

|

||

||

||

|

||

||

|

||

||

Customizing the SSL connection for a command-line client

Tivoli Workload Scheduler command-line clients connect to the connector throughHTTP or HTTPS. The default connection type is HTTPS. If the command-lineconnects through a proxy, use the HTTP connection protocol as HTTPS is notsupported for this type of configuration.

You configure the connection protocol as described in “Configuring command-lineclient access authentication” on page 70. If you have previously not been using SSLfor the command line client access, you will need to change at least the followingparameters:

proxy Specify the IP address or the server name for the proxy server.

proxy portSpecify the listening port of the proxy server.

protocolSpecify the protocol type as HTTP or HTTPS.

port Specify the port required by the protocol you set in the protocol option.The default is 31115 for HTTP and 31116 for HTTPS.

The HTTPS connection protocol offers the following additional security features:v Data encryption between the command-line utility and the connectorv Optional server authentication by validating the server certificates

You can activate optional server authentication in one of the following ways:v “Configuring SSL using the predefined certificate”v “Configuring multiple SSL communication instances”v “Using a customized certificate” on page 200

Configuring SSL using the predefined certificate

To customize the SSL connection for the command-line client using the predefinedcertificate, perform the following steps:1. Stop the embedded WebSphere Application Server using the conman

stopappserver command.2. Extract the certificate from the TWSServerKeyFile.jks keystore:

keytool -export-alias tws-rfc-file server.crt-keystore TWSServerKeyFile.jks-storepass default

3. Copy the .crt certificate to each workstation that has a command-line clientinstalled.

4. Set the cli ssl server auth and cli ssl server certificate command-lineclient options in the localopts file. See “Setting local options” on page 23.

5. Start the embedded WebSphere Application Server using the conmanstartappserver command.

Configuring multiple SSL communication instances

To customize the SSL connection for the command-line client for multipleconnections to WebSphere Application Server, perform the following steps:


1. Stop WebSphere Application Server using the conman stopappservercommand.

2. Extract a certificate from TWSServerKeyFile.jks keystore for each instance.keytool -export

-alias tws-rfc-file server.crt-keystore ServerKeyFile.jks-storepass default

.3. Extract the hash number for each exported certificate:

openssl x509-hash-noout-in keyname

4. Rename each certificate file with the exported key.5. Copy the renamed certificates to each workstation that has a command-line

client installed.6. Set the cli ssl server auth and cli ssl trusted dir command-line client

options in the localopts file. See “Setting local options” on page 23.7. Start the WebSphere Application Server using the conman startappserver

command.

Using a customized certificate

To customize the SSL certificate and keystore, perform the following steps:1. Create a new RSA and extract the key for the server keystore

TWSServerKeyFile.jks.2. Follow the steps in “Customizing the SSL connection for the Dynamic

Workload Console” on page 196.3. Follow the steps in “Configuring SSL using the predefined certificate” on page

199.

Note: When you want to customize certificates for multiple instances, performthese steps for each instance.

Working across firewallsIn the design phase of a Tivoli Workload Scheduler network, the administratormust know where the firewalls are positioned in the network, which fault-tolerantagents and which domain managers belong to a particular firewall, and which arethe entry points into the firewalls. When this has been clearly understood, theadministrator should define the behindfirewall attribute for some of theworkstation definitions in the Tivoli Workload Scheduler database. In particular, ifa workstation definition is set with the behindfirewall attribute to ON, this meansthat there is a firewall between that workstation and the Tivoli Workload Schedulermaster domain manager. In this case, the workstation-domain manager link is theonly link allowed between the workstation and its domain manager.

All Tivoli Workload Scheduler workstations should be defined with thebehindfirewall attribute if the link with the corresponding domain manager, orwith any domain manager in the Tivoli Workload Scheduler hierarchy right up tothe master domain manager, is across a firewall.


When mapping an IBM Tivoli Workload Scheduler network over an existingfirewall structure, it does not matter which fault-tolerant agents and which domainmanagers are on the secure side of the firewall and which ones are on the nonsecure side. Firewall boundaries should be the only concern. For example, if themaster domain manager is in a non secure zone and some of the domain managersare in secured zones, or vice versa, does not make any difference. The firewallstructure must always be considered starting from the master domain manager andfollowing the Tivoli Workload Scheduler hierarchy, marking all the workstationsthat have a firewall between them and their corresponding domain manager.

For all workstations with behindfirewall set to ON, the conman start and stopcommands on the workstation, and the showjobs commands are sent following thedomain hierarchy, instead of making the master domain manager or the domainmanager open a direct connection to the workstation. This makes a significantimprovement in security.

This attribute works for multiple nested firewalls as well. For extended agents, youcan specify that an extended agent workstation is behind a firewall by setting thebehindfirewall attribute to ON, on the host workstation. The attribute is read-onlyin the plan; to change it in the plan, the administrator must update it in thedatabase and then recreate the plan.

See the Tivoli Workload Scheduler: User's Guide and Reference for details on how to setthis attribute.

Configuring Tivoli Workload Scheduler to use LDAP

To use LDAP configured in SSL with Tivoli Workload Scheduler, perform thefollowing steps:1. Import the LDAP public key in the truststore of the Tivoli Workload Scheduler

server, by storing it in the TWSServerTrustFile.jks file located inTWA_home/eWAS/profiles/TIPProfile/etc.

2. Import the LDAP public key in the truststore of the Tivoli Workload Schedulerclient, by storing it in the TWSClientTrustFile.jks file located inTWA_home/eWAS/profiles/TIPProfile/etc.

FIPS complianceThis section describes Federal Information Processing Standards (FIPS) compliance.It is divided into the following topics:v “FIPS overview” on page 202v “Using FIPS certificates” on page 202v “Configuring SSL to be FIPS-compliant” on page 206v “Configuring DB2 for FIPS” on page 209v “Using Dynamic Workload Console and FIPS” on page 214v “Configuring dynamic workload broker for FIPS” on page 215v “Configuring LDAP for FIPS” on page 216v “Finding the GSKit version on agents running on UNIX and Linux operating

systems” on page 216


|

||

|||

|||

FIPS overviewFederal Information Processing Standards (FIPS) are standards and guidelinesissued by the National Institute of Standards and Technology (NIST) for federalgovernment computer systems. FIPS are developed when there are compellingfederal government requirements for standards, such as for security andinteroperability, but acceptable industry standards or solutions do not exist.Government agencies and financial institutions use these standards to ensure thatthe products conform to specified security requirements.

Tivoli Workload Automation uses cryptographic modules that are compliant withthe Federal Information Processing Standard FIPS-140-2. Certificates used internallyare encrypted using FIPS-approved cryptography algorithms. FIPS-approvedmodules can optionally be used for the transmission of data.

To satisfy the FIPS 140-2 requirement, you must use IBM Global Security Kit(GSKit) version 7d runtime dynamic libraries instead of OpenSSL. GSKit uses IBMCrypto for C version 1.4.5 which is FIPS 140-2 level 1 certified by the certificatenumber 755. See http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2007.htm. IBM Java JSSE FIPS 140-2 Cryptographic is another module usedby Tivoli Workload Automation. It has the certificate number 409.

If you are currently using SSL for secure connections across the network, to ensureFIPS compliance, you must use GSKit for secure connections instead of OpenSSLToolkit. GSKit is automatically installed with Tivoli Workload Scheduler. It is basedon dynamic libraries and offers several utilities for certificate management.

To comply with FIPS, all components of Tivoli Workload Automation must beFIPS-compliant. You must use Dynamic Workload Console or the Tivoli WorkloadScheduler command-line as the interface to Tivoli Workload Scheduler.Additionally, you must use DB2 as your Tivoli Workload Scheduler database.

If FIPS compliance is not of concern to your organization, you can continue to useSSL for secure connections across your network.

To set FIPS compliance for your network, perform the procedures described in thefollowing sections:v To create FIPS certificates, see “Using FIPS certificates.”v To configure SSL for FIPS-compliance, see “Configuring SSL to be

FIPS-compliant” on page 206.v To configure your DB2 database for FIPS-compliance, see “Configuring DB2 for

FIPS” on page 209.

Using FIPS certificates

To ensure your network is FIPS-compliant, create FIPS certificates as follows:v If you do not already have SSL certificates, see “Using fresh FIPS certificates” on

page 203.v If you already have SSL certificates but are switching to GSKit, see “Switching

from OpenSSL to GSKit” on page 204.

If you are using FIPS certificates, you must use SSL parameters for communicationover the network. During the installation or upgrade to Tivoli Workload Schedulerversion 8.5.1, note that default SSL certificates are located in the followingdirectories:


http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2007.htm

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2007.htm

TWS_InstallDir\TWS\ssl\GSKitTWS_InstallDir\TWS\ssl\OpenSSL

Using fresh FIPS certificatesCreate FIPS certificates for communication between workstations by using the –fipsoption in the GSKit command line utility. You can create FIPS certificates in thefollowing ways:v Use the default FIPS certificates existing on each Tivoli Workload Scheduler

agent in the network. Note that the default FIPS certificates are not secure.v Create your own secure FIPS certificates. See “Creating your own FIPS

certificates.”

Creating your own FIPS certificates: Use the gsk7capicmd command line utilityto:v Create your own Certificate Authority (CA).v Create a self-signed CA certificate (x.509 structure) for your CA.v Export the CA certificate in PEM format.

Creating your own Certificate Authority: Create the CA on any workstation in yournetwork. Run the following steps only once to create a CA that will be used eachtime a new certificate needs to be created and signed.1. Enter the following command to create the CMS key database “ca.kdb” with

password “password00” that expires after 1000 days.gsk7capicmd -keydb -create -db ca.kdb -pw password00 -stash -expire 1000 -fips

2. Enter the following command to create the self-signed certificate with label“CA certificate” using the distinguish name “CN=CAcertificate,O=IBM,OU=TWS,C=IT”. The certificate expires after 1000 days.gsk7capicmd -cert -create -db ca.kdb -pw password00 -label "CA certificate"

-size 1024 -expire 1000 -dn "CN=CA certificate,O=IBM,OU=TWS,C=IT"

3. Enter the following command to extract the CA certificate into external file“ca.crt”. The certificate is addressed by the corresponding label.gsk7capicmd -cert -extract -db ca.kdb -pw password00 -label "CA certificate"

-target CA.crt

This file will contain the public certificate of the certificate authority.

Creating a certificate for the Tivoli Workload Scheduler agent: Perform the followingsteps to create certificates that are signed by a local common trusted CA on everyTivoli Workload Scheduler agent in your network.1. Enter the following command to create a default CMS key database client.kdb”

with password “password02” that expires after 1000 days. The password is alsostored in stash file “client.sth”.gsk7capicmd -keydb -create -db client.kdb -pw password02

-stash -expire 1000 -fips

2. Enter the following command to add the CA certificate as trusted in the CMSkey database. The label “CA certificate client” is used to address that certificate.gsk7capicmd -cert -add -db client.kdb -pw password02

-label "CA certificate client" -trust enable -file CA.crt-format ascii -fips

3. Enter the following command to create the client certificate request based on1024 bits key, with label “Client TWS85 Certificate” and distinguish name“CN=Client TWS85,O=IBM,OU=TWS,C=IT”. The certificate request “client.csr” isgenerated and the private key is created in the key database client.kdb.


gsk7capicmd -certreq -create -db client.kdb -pw password02-label "Client TWS85 Certificate" -size 1024 -file client.csr–dn "CN=Client TWS85,O=IBM,OU=TWS,C=IT" -fips

4. Enter the following command so that the CA signs the client's certificaterequest and generates a new signed in file “client.crt”.gsk7capicmd -cert -sign -db ca.kdb -pw password00 -label "CA certificate"

-target client.crt -expire 365 -file client.csr -fips

5. Enter the following command to import the signed certificate “client.crt” in theCMS key database “client.kdb”.gsk7capicmd -cert -receive -db client.kdb -pw password02 -file client.crt -fips

You can repeat these steps above for all agents or you can use the same certificatefor all agents, depending on your security policies and Tivoli WorkloadAutomation localopts configurations.

Switching from OpenSSL to GSKit

This section describes how to migrate your OpenSSL certificates to GSKitcertificates.

The following is a list of certificate formats that can be migrated to the GSKitformat, KDB:v PEM: Used by OpenSSLv JKS: Used by Java and WebSphere Application Serverv PKCS12: Used by Microsoft applications and Internet Explorer

To migrate certificates, you may use one or more of the following tools:v gsk7cmd: Java command line provided by GSKitv gsk7capicmd: Native command line provided by GSKitv openssl: Native command line provided by OpenSSLv ikeyman: Optional graphical interface provided by GSKitv keytool: Optional graphical interface provided by Java Virtual Machine (JVM)

Note: Be sure to backup your original certificates before migrating them to GSKitformat.

To migrate your certificates, perform the following steps:1. “Configuring the tool environment”2. “Migrating the certificates” on page 205

Configuring the tool environment: This section describes the commands youmust run to configure gsk7cmd, gsk7capicmd, and openssl.

Configuring gsk7cmd:

UNIX

export JAVA_HOME=/opt/IBM/TWA/eWAS/java/jre

export CLASSPATH= /opt/IBM/TWA/eWAS/java/bin:

/opt/IBM/TWA/eWAS/java/lib

Windows

set JAVA_HOME=C:\Program Files\IBM\TWA\eWAS\java\jre


set CLASSPATH= C:\Program Files\IBM\TWA \eWAS\java\bin; C:\ProgramFiles\IBM\TWA \eWAS\java\lib

Configuring gsk7capicmd: set PATH=C:\Program Files\IBM\TWA\TWS\GSkit\7d\lib;C:\Program Files\IBM\TWA\TWS\GSkit\7d\bin;%PATH%

Configuring openssl:

UNIX tws_env.sh

Windowstws_env.cmd

Migrating the certificates: This section describes the commands you must run tomigrate certificates to the FIPS-compliant format, KDB.

Note that PEM format cannot be directly converted to KDB format; you must firstconvert PEM to PKCS12 and then to KDB.

The following list describes the command you must run to convert from oneformat to another:

JKS format to KDB format

gsk7cmd -keydb -convert -db TWSClientKeyFile.jks -pw default-old_format jks -new_format cms

gsk7cmd -keydb -convert -db TWSClientTrustFile.kdb -pw default-old_format cms -new_format jks

PKCS12 format to KDB formatgsk7capicmd -cert -export -target TWSClientKeyFile_new.kdb -dbTWSClientKeyFileP12.P12 -fips -target_type cms -type pkcs12

PKCS12 format to PEM formatopenssl pkcs12 -in TWSClientKeyFileP12.P12 -out TWSClientKeyFile.pem

PEM format to PKCS12 formatopenssl pkcs12 -export -in TWSClientKeyFile.pem -out cred.p12

KDB format to PKCS12 formatgsk7capicmd -cert -export -db TWSClientKeyFile.kdb -targetTWSClientKeyFileP12.P12 -fips -target_type pkcs12 -type cms

Converting PEM certificates to CMS certificates: This section describes the procedureto convert PEM (OpenSSL) certificates to CMS (GSKit) certificates. The examples inthis section use the following input and output files.

Input files

Personal certificate file: CPU1.crtPersonal key of certificate file: CPU1.keyCertificate of CA file: TWSca.crtStash file: CPU1.sth

Output files

Keystore database file: TWS.kdbStash file: TWS.sthLabel of your certificate: CPU1


To migrate OpenSSL certificates to GSKit certificates, perform the followingprocedure:1. Merge the public and private keys in a new temporary file called all.pem by

running the following commands:

UNIX cat CPU2.crt CPU2.key > all.pem

Windowstype CPU1.crt CPU1.key > all.pem

2. If you do not already know the password, extract it from the stash file byrunning openssl base64 -d -in CPU1.sth.

3. Choose a password for the new keystore database. You can reuse the oldpassword.

4. Choose a label for your personal certificate and personal key (in this example,CPU1) and create the PKCS12 database that contains the labels. You use thename, CPU1, as the label of the new keystore database. To create the PKCS12database, run the following:openssl pkcs12 -export -in all.pem -out TWS.p12 -name CPU1 -passin pass:

password1 -passout pass:password2

where password1 is the password extracted from the stash file and password2 isis the new password to manage the new keystore database.

5. Convert the PKCS12 database from TWS.p12 to the CMS database, TWS.kdb byrunning the following:gsk7capicmd -cert -import -target TWS.kdb -db TWS.p12 -target_type cms

-type pkcs12 -label CPU1 -target_pw "password2" -pw "password3"

where password2 is the old password that you extracted from the stash file,CPU1.sth and password3 is the new password.

6. Choose a label for your Certification Authority contained in TWSca.crt. For thisexample, it is TWSca.

7. Add the certificate of the Certification Authority into your TWS.kdb file byrunning:gsk7capicmd -cert -add -db TWS.kdb -label TWSca -trust -file TWSca.crt

-format ascii -pw "password"

8. Delete all .pem files.

Configuring SSL to be FIPS-compliant

To configure SSL to be FIPS-compliant, perform the following procedures:v Set localopts parameters. See “Setting localopts parameters for FIPS” on page

207.v Configure embedded WebSphere Application Server. See “Configuring

embedded WebSphere Application Server for FIPS” on page 207.v Configure the Tivoli event integration facility port. See “Configuring the Tivoli

event integration facility port” on page 209.

Note:

If you are using dynamic workload broker for dynamic scheduling in yournetwork, note that the workstation of type BROKER does not support SSL. AllTivoli Workload Scheduler workstations must communicate with theworkstation of type BROKER using TCP/IP protocol.


Setting localopts parameters for FIPS

To set your environment for FIPS, set the following local option on every TivoliWorkload Scheduler agent in the network.

SSL Fips enabled = yes

The following example applies to a Windows agent. Set the following local optionsfor the engine:

SSL keystore file = "<TWA_home>\TWS\ssl\GSKit\TWSClientKeyStore.kdb"SSL certificate keystore label = "client"SSL keystore pwd = "<TWA_home>\TWS\ssl\GSKit\TWSClientKeyStore.sth"

where <TWA_home> is the installation directory of the instance of Tivoli WorkloadAutomation where the agent is installed.

Set the following local options for the CLI:

CLI SSL keystore file ="<TWA_home>\TWS\ssl\GSKit\TWSClientKeyStore.kdb"

CLI SSL certificate keystore label = "client"CLI SSL keystore pwd =

"<TWA_home>\TWS\ssl\GSKit\TWSClientKeyStore.sth"

where <TWA_home> is the installation directory of the instance of Tivoli WorkloadAutomation where the agent is installed.

Note: On Windows workstations, the user, SYSTEM, must have read-permissionsto read the GSKit FIPS certificates.

Configuring embedded WebSphere Application Server for FIPS

To be FIPS-compliant, you must configure embedded WebSphere ApplicationServer for Tivoli Workload Scheduler.

The section describes how to:v Configure embedded WebSphere Application Server for Tivoli Workload

Scheduler. See “Configuring embedded WebSphere Application Server for TivoliWorkload Scheduler.”

v Configure the Tivoli event integration facility port. See “Configuring the Tivolievent integration facility port” on page 209.

Configuring embedded WebSphere Application Server for Tivoli WorkloadScheduler: To configure embedded WebSphere Application Server for FIPScompliance, perform the following steps:1. In the WebSphere Application Server administration interface, click Security >

SSL certificate and key management. Select Use the United States FederalInformation Processing Standard (FIPS) algorithms and click Apply.Alternatively, you can use wastools, running changeSecurityProperties tochange the following parameter:useFIPS=true

2. In the profile_root/properties/ssl.client.props file, set the followingparameters:v com.ibm.security.useFIPS=true


|

||

|

||

|||

||

|

|||||

||

||

|

v com.ibm.ssl.protocol=SSL_TLS

3. If you have an administrative client that uses a SOAP connector, add thefollowing line to the profile_root/properties/soap.client.props file:com.ibm.ssl.contextProvider=IBMJSSEFIPS

4. Edit the SDK java.security file located in the WASHOME/java/jre/lib/securitydirectory to insert the IBMJCEFIPS provider(com.ibm.crypto.fips.provider.IBMJCEFIPS). IBMJCEFIPS must precede theIBMJCE provider in the provider list.The following is an example of the edited SDK java.security file:security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPSsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.jsse.IBMJSSEProvidersecurity.provider.4=com.ibm.jsse2.IBMJSSEProvider2security.provider.5=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.6=com.ibm.security.cert.IBMCertPathsecurity.provider.7=com.ibm.crypto.pkcs11.provider.IBMPKCS11security.provider.8=com.ibm.security.cmskeystore.CMSProvidersecurity.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

The following is an example of the edited java.security file if you are using theOracle Java SE Development Kit:security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPSsecurity.provider.3=com.ibm.crypto.provider.IBMJCEsecurity.provider.4=com.ibm.jsse.IBMJSSEProvidersecurity.provider.5=com.ibm.jsse2.IBMJSSEProvider2security.provider.6=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.7=com.ibm.security.cert.IBMCertPathsecurity.provider.8=com.ibm.i5os.jsse.JSSEProvider#security.provider.8=com.ibm.crypto.pkcs11.provider.IBMPKCS11security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

5. Restart the WebSphere Application Server.

Note: For additional information about WebSphere Application Server and FIPS,see the WebSphere Application Server documentation.

Unconfiguring the FIPS provider: To unconfigure the FIPS provider, reverse thechanges that you made in “Configuring embedded WebSphere Application Serverfor FIPS” on page 207. After you reverse the changes, verify that you have madethe following changes to the ssl.client.props, soap.client.props, and java.securityfiles:v In the ssl.client.props file, change the com.ibm.security.useFIPS value to false.v In the java.security file, change the FIPS provider to a non-FIPS provider.v If you are using the SDK java.security file, change the first provider to a

non-FIPS provider as shown in the following example:#security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPSsecurity.provider.1=com.ibm.crypto.provider.IBMJCEsecurity.provider.2=com.ibm.jsse.IBMJSSEProvidersecurity.provider.3=com.ibm.jsse2.IBMJSSEProvider2security.provider.4=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.5=com.ibm.security.cert.IBMCertPath#security.provider.6=com.ibm.crypto.pkcs11.provider.IBMPKCS11

v If you are using the Oracle JDK java.security file, change the third provider to anon-FIPS provider as shown in the following example:security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.ibm.security.jgss.IBMJGSSProvider#security.provider.3=com.ibm.crypto.fips.provider.IBMJCEFIPSsecurity.provider.3=com.ibm.crypto.provider.IBMJCE


security.provider.4=com.ibm.jsse.IBMJSSEProvidersecurity.provider.5=com.ibm.jsse2.IBMJSSEProvider2security.provider.6=com.ibm.security.cert.IBMCertPath#security.provider.7=com.ibm.crypto.pkcs11.provider.IBMPKCS11

v This step applies only if you added the default JSSE socket factories parametersto the SDK java.security file as described in “Configuring DB2 for FIPS.” If youadded them, remove the following parameters:ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImplssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl

Configuring the Tivoli event integration facility port

The Tivoli event integration facility port for SSL, eventProcessorEIRSSLPort, isused in event management. For the Tivoli event integration facility port tocommunicate in FIPS mode, you must first configure embedded WebSphereApplication Server for FIPS. See “Configuring embedded WebSphere ApplicationServer for Tivoli Workload Scheduler” on page 207.

To configure the Tivoli event integration facility port for SSL, perform thefollowing steps:1.

Set the global option for the port using optman. Set the port as follows:eventProcessorEIFSSLPort / ef = portnumber

where portnumber is the port number of any free port on your network.2. To update the Symphony file, run JnextPlan -for 0000.3. Restart the EventProcessor using the conman stopevtp and conman startevtp

commands.4. Restart the Tivoli Workload Scheduler monitoring engine with the conman

commands, stopmon and startmon.

Configuring DB2 for FIPSTo configure DB2 for FIPS compliance, perform one of the following proceduresdepending on the DB2 version you are using:v “Configuring DB2, version 9.5”v “Configuring DB2, version 9.7, fix pack 2 and later” on page 211v “Configuring the DB2 connection to Tivoli Workload Scheduler” on page 213

Note: If you want to create your own DB2 certificates, see the DB2 documentation.

Configuring DB2, version 9.5

To configure DB2 version 9.5, for FIPS compliance, perform the followingprocedure:1. Ensure that the path to the GSKit libraries is included in the relevant

environment variables. The names of the environment variables varydepending on the operating system, as follows:

UNIX and LinuxLIBPATH, LD_LIBRARY_PATH, or SHLIB_PATH environmentvariables. Specify this information in the .profile file for the DB2instance owner.

WindowsPATH environment variable. For example, c:\ProgramFiles\IBM\gsk7\lib.


||

|

|

|

|

||

|||

||||

|||

GSKit is automatically included when you install the DB2 database system.

On Windows 32-bit operating systemsthe GSKit libraries are located in C:\Program Files\IBM\GSK8\lib. Inthis case, the system PATH must include C:\ProgramFiles\IBM\GSK8\lib.

On Windows 64-bit operating systemsthe 64-bit GSKit libraries are located in C:\ProgramFiles\IBM\GSK8\lib64 and the 32-bit GSKit libraries are located inC:\Program Files (x86)\IBM\GSK8\lib.

On UNIX and Linux operating systems,the GSKit libraries are located in sqllib/lib. Therefore, the LIBPATH,SHLIB_PATH or LD_LIBRARY_PATH environment variables mustinclude sqllib/lib.

On non-Windows operating systemsthe DB2 database manager installs GSKit locally, and for a giveninstance, the GSKit libraries might be located in sqllib/lib orsqllib/lib64.

2. In INSTHOME, create the file SSLconfig.ini as follows:

UNIX and LinuxINSTHOME/cfg/SSLconfig.ini

WindowsINSTHOME/SSLconfig.ini

where INSTHOME is the home directory of the instance. It is recommendedthat file permission is set to limit access to the SSLconfig.ini file because the filecontains sensitive data, for example, password information.The following is an example of an SSLconfig.ini file:DB2_SSL_KEYSTORE_FILE=/tools/keystores/DB2/TWSClientKeyStore.kdbDB2_SSL_KEYSTORE_PW=yyyyyDB2_SSL_LISTENER=nnnnnDB2_SSL_KEYSTORE_LABEL=zzzzz

wherev TWSClientKeyStore.kdb is the fully-qualified file name of the KeyStore that

stores the DB2 certificate, and the trusted certificates, for example thecertificates for the eWAS server to connect to. This KeyStore can be the sameon you specified in the localopts parameters. See “Setting localoptsparameters for FIPS” on page 207. Note that it must be recognized by theJKS WebSphere Application Server certificate.

v yyyy is the password of the KeyStore that stores the Server Certificate.v nnnnn is the port number used by DB2 . This port must be the same port as

the SSL port.v zzzzz is the label for the Server Certificate.

3. Configure SSL with the command db2set DB2COMM=SSL.

Note: During the installation of a Tivoli Workload Scheduler master domainmanager or backup master domain manager, it is necessary to enable theDB2 TCPIP port. DB2 can support both TCP/IP and SSL communicationsprotocols at the same time. The DB2 administrator can set the TCPIPport with the command db2set DB2COMM=TCPIP, SSL. Use this commandif you are installing a Tivoli Workload Scheduler master domain


|

||||

||||

||||

||||

|

||

||

|||

|

||||

|

||||||

|

||

|

|

||||||

manager or backup master domain manager and already have aFIPS-enabled instance of DB2. After installation, you can choose to resetDB2COMM with only SSL.

4. Insert the following default JSSE socket factories parameters in the java.securityfile of the Tivoli Workload Scheduler WebSphere Application Server:ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImplssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl

5. Restart DB2.

Note: It is not necessary to update the DB2 JVM. This is because you alreadyupdated the JVM of the embedded WebSphere Application Server in theprocedure described in “Configuring embedded WebSphere ApplicationServer for FIPS” on page 207.

For more information about how to configure DB2 to be FIPS compliant, see theDB2 documentation that describes how to configure Secure Sockets Layer (SSL)support in a DB2 instance.

Configuring DB2, version 9.7, fix pack 2 and later

To configure DB2, version 9.7, fix pack 2 and later, for FIPS compliance, performthe following procedure:1. Ensure that the path to the GSKit libraries is included in the relevant

environment variables. The names of the environment variables varydepending on the operating system, as follows:

UNIX and LinuxLIBPATH, LD_LIBRARY_PATH, or SHLIB_PATH environmentvariables. Specify this information in the .profile file for the DB2instance owner.

WindowsPATH environment variable. For example, c:\ProgramFiles\IBM\gsk7\lib.

GSKit is automatically included when you install the DB2 database system.

On Windows 32-bit operating systemsthe GSKit libraries are located in C:\Program Files\IBM\GSK8\lib. Inthis case, the system PATH must include C:\ProgramFiles\IBM\GSK8\lib.

On Windows 64-bit operating systemsthe 64-bit GSKit libraries are located in C:\ProgramFiles\IBM\GSK8\lib64 and the 32-bit GSKit libraries are located inC:\Program Files (x86)\IBM\GSK8\lib.

On UNIX and Linux operating systems,the GSKit libraries are located in sqllib/lib. Therefore, the LIBPATH,SHLIB_PATH or LD_LIBRARY_PATH environment variables mustinclude sqllib/lib.

On non-Windows operating systemsthe DB2 database manager installs GSKit locally, and for a giveninstance, the GSKit libraries might be located in sqllib/lib orsqllib/lib64.


|||

||

||

|

||||

|||

||

|||

||||

|||

|

||||

||||

||||

||||

2. To set up your DB2 server for SSL support, log in as the DB2 instance ownerand set the following configuration parameters and the DB2COMM registryvariable. Use the db2 update dbm cfg parameter_name using parameter_valuecommand, where

parameter_nameIs the name of the parameter to be set.

parameter_valueIs the value of the parameter to be set.

a. Set the ssl_svr_keydb configuration parameter to the fully qualified path ofthe key database file. For example:C:\TWS\installations\tws850cli\TWS\ssl\gskit\TWSClientKeyStore.kdb

where:

TWSClientKeyStore.kdbIs the fully-qualified file name of the KeyStore that stores the DB2certificate, and the trusted certificates, for example the certificatesfor the eWAS server to connect to. This KeyStore can be the sameone you specified in the localopts parameters. See “Setting localoptsparameters for FIPS” on page 207. Note that it must be recognizedby the JKS WebSphere Application Server certificate.

If ssl_svr_keydb is null (unset), SSL support is not enabled.b. Set the ssl_svr_stash configuration parameter to the fully qualified path of

the stash file. For example:C:\TWS\installations\tws850cli\TWS\ssl\gskit\TWSClientKeyStore.sth

If ssl_svr_stash is null (unset), SSL support is not enabled.c. Set the ssl_svr_label configuration parameter to the label of the digital

certificate of the server. If ssl_svr_label is not set, the default certificate inthe key database is used. If there is no default certificate in the keydatabase, SSL is not enabled. For example:"client"

d. Set the ssl_svcename configuration parameter to the port that the DB2database system listens on for SSL connections. If TCP/IP and SSL are bothenabled (the DB2COMM registry variable is set to 'TCPIP, SSL'), setssl_svcename to a different port than the port to which svcename is set.The svcename configuration parameter sets the port that the DB2 databasesystem listens on for TCP/IP connections. If you set ssl_svcename to thesame port as svcename, neither TCP/IP or SSL are enabled. If ssl_svcenameis null (unset), SSL support is not enabled.

Note:

1) In HADR environments, do not set hadr_local_svc on theprimary or standby database system to the same value as you setfor ssl_svcename. Also, do not set hadr_local_svc to the samevalue as svcename, or svcename plus one.

2) When the DB2COMM registry variable is set to 'TCPIP,SSL', ifTCPIP support is not properly enabled, for example due to thesvcename configuration parameter being set to null, the errorSQL5043N is returned and SSL support is not enabled.

e. (Optional) If you want to specify which cipher suites the server can use, setthe ssl_cipherspecs configuration parameter. If you leave ssl_cipherspecs as


||||

||

||

||

|

|

|||||||

|

||

|

|

||||

|

||||||||

|

||||

||||

||

null (unset), this allows GSKit to pick the strongest available cipher suitethat is supported by both the client and the server.

f. Add the value SSL to the DB2COMM registry variable. For example:db2set -i db2inst1 DB2COMM=SSL

The database manager can support multiple protocols at the same time. Forexample, to enable both TCP/IP and SSL communication protocols:db2set -i db2inst1 DB2COMM=SSL,TCPIP

where:

db2inst1Is the DB2 instance name.

Note: During the installation of a Tivoli Workload Scheduler master domainmanager or backup master domain manager, it is necessary to enablethe DB2 TCPIP port. DB2 can support both TCP/IP and SSLcommunications protocols at the same time. The DB2 administratorcan set the TCPIP port with the command db2set DB2COMM=TCPIP,SSL. Use this command if you are installing a Tivoli WorkloadScheduler master domain manager or backup master domain managerand already have a FIPS-enabled instance of DB2. After installation,you can choose to reset DB2COMM with only SSL.

g. Restart the DB2 instance. For example:db2stopdb2starts

3. Insert the following default JSSE socket factories parameters in the java.securityfile of the Tivoli Workload Scheduler WebSphere Application Server:ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImplssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl

4. Restart DB2.

Note: It is not necessary to update the DB2 JVM. This is because you alreadyupdated the JVM of the embedded WebSphere Application Server in theprocedure described in “Configuring embedded WebSphere ApplicationServer for FIPS” on page 207.

For more information about how to configure DB2 to be FIPS compliant, see theDB2 documentation that describes how to configure Secure Sockets Layer (SSL)support in a DB2 instance.

Configuring the DB2 connection to Tivoli Workload Scheduler

After configuring DB2, you must configure Tivoli Workload Scheduler tocommunicate with the new settings of DB2. Perform the following procedure:1. Modify the DB2 DataSource properties in wastools by running

showDataSourceProperties and changeDataSourceProperties to include thefollowing parameters:DB2Type4PortNumber=nnnnnDB2Type4SslConnection=true

where nnnnn is the SSL DB2 port number.2. Restart the WebSphere Application Server.


||

|

|

||

|

|

||

|||||||||

|

||

||

||

|

Using Dynamic Workload Console and FIPS

To ensure that you connect to Dynamic Workload Console using FIPS, perform thefollowing:1. Enable Transport Layer Security (TLS) in your browser as follows:

v To enable TLS in Internet Explorer, open the browser and click Tools >Internet Options. On the Advanced tab, select Use TLS 1.0.

v To enable TLS in Mozilla Firefox, open the browser and click Tools >Options>Advanced. On the Encryption tab, select Use TLS 1.0.

v To enable TLS on other internet browsers, see the product documentation forthat browser.

2. Depending on your configuration, perform one of the following procedures:

If you have a standalone instance of Dynamic Workload Console onembedded WebSphere Application Server:

a. Configure FIPS on the embedded WebSphere Application Server ofDynamic Workload Console. See “Configuring embeddedWebSphere Application Server for FIPS” on page 207.

b. Restart the embedded WebSphere Application Server.

If you have an instance of Dynamic Workload Console that shares aninstance of Tivoli Workload Scheduler embedded WebSphere ApplicationServer:

a. Ensure that the Tivoli Workload Scheduler embedded WebSphereApplication Server is FIPS-compliant. See “Configuring embeddedWebSphere Application Server for FIPS” on page 207.

b. In the Tivoli Workload Scheduler wastools, runshowDataSourceProperties to ensure the following parameters areset:DB2Type4PortNumber=nnnnnDB2Type4SslConnection=true

where nnnnn is the SSL DB2 port number.c. Restart the embedded WebSphere Application Server.

If you have Dynamic Workload Console on an external WebSphereApplication Server:

a. Ensure that the WebSphere Application Server is FIPS-compliant.See “Configuring embedded WebSphere Application Server forFIPS” on page 207.

If you have Dynamic Workload Console with a DB2 settings repository:

a. Ensure that DB2 is FIPS-compliant. See “Configuring DB2 for FIPS”on page 209.

b. To ensure the required SSL connection between DB2 and DynamicWorkload Console, perform the following procedure:1) Go to the Tivoli Workload Scheduler wastools directory and

modify the TDWCDataSource properties to include thefollowing parameters:useSslConnection=truedeleteAndRecreate=truedatabasePort=nnnnn

where nnnnn is the SSL DB2 port number.


|

||

||

|||

|||

|

2) Run installTDWCDataSource by entering the followingcommands:

UNIX and Linux operating systemsInstallTDWCDataSource.sh TDWCDataSource.properties

Windows operating systemsInstallTDWCDataSource.bat TDWCDataSource.properties

c. Restart the embedded WebSphere Application Server.3. If you are using Dynamic workload broker, set a secure connection by

performing the following:a. In Dynamic Workload Console, access Tivoli Dynamic Workload Broker and

expand the Configuration menu.b. Click Server Connections.c. In the Server Connections screen, select Use Secure Connection.d. Click OK.

Note: To enable communication between Dynamic Workload Console and DB2,configure the Java system properties in Dynamic Workload Console to usethe trustStore. To do this, set the following Java system properties:javax.net.ssl.trustStorejavax.net.ssl.trustStorePassword

For more information, see the DB2 documentation.

Configuring dynamic workload broker for FIPS

If you are using the dynamic workload broker component in your network,perform the following configurations:v Configure the ita.ini file of every agent that will communicate with the dynamic

workload broker component. Ensure that the ssl_port is set and set fips_enable =1.

v If you are using Dynamic Workload Console, set a secure connection byperforming the following:1. In Dynamic Workload Console, access dynamic workload broker and expand

the Configuration menu.2. Click Server Connections.3. In the Server Connections screen, select Use Secure Connection.4. Click OK.

Configuring batch reports for FIPS

To configure batch reports for FIPS compliance, perform the following steps:v Import the FIPS certificate from the database server to a Java trustStore on the

client. Use the Java keytool utility to import the certificate into the trustStore.v Edit the SDK java.security file located in the INSTALL_DIR/java/jre/lib/

security directory to insert the IBMJCEFIPS provider(com.ibm.crypto.fips.provider.IBMJCEFIPS). IBMJCEFIPS must precede theIBMJCE provider in the provider list.The following is an example of the edited SDK java.security file:security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPSsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.jsse.IBMJSSEProvider


||

||

||

|

security.provider.4=com.ibm.jsse2.IBMJSSEProvider2security.provider.5=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.6=com.ibm.security.cert.IBMCertPathsecurity.provider.7=com.ibm.crypto.pkcs11.provider.IBMPKCS11security.provider.8=com.ibm.security.cmskeystore.CMSProvidersecurity.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

The following is an example of the edited java.security file if you are using theOracle Java SE Development Kit:security.provider.1=sun.security.provider.Sunsecurity.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPSsecurity.provider.3=com.ibm.crypto.provider.IBMJCEsecurity.provider.4=com.ibm.jsse.IBMJSSEProvidersecurity.provider.5=com.ibm.jsse2.IBMJSSEProvider2security.provider.6=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.7=com.ibm.security.cert.IBMCertPathsecurity.provider.8=com.ibm.i5os.jsse.JSSEProvider#security.provider.8=com.ibm.crypto.pkcs11.provider.IBMPKCS11security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

v Verify that the keystore.type parameter is the same as the value specified fortype of the keystore in the config.file. The default value is JKS.

Configuring LDAP for FIPS

To be FIPS-compliant if you are using an LDAP server, before configuring LDAP,edit the security.xml file. Edit the following value:"com.ibm.ssl.contextProvider" value="IBMJSSEFIPS"

Finding the GSKit version on agents running on UNIX andLinux operating systems

To find which version of GSKit runs on your agent, run the gsk7ver command.

On UNIX and Linux, you can optionally run the ita_props.sh script to set theenvironment to /usr/Tivoli/TWS/GSKit/7d/bin, so that you can run this commanddirectly without having to specify the relative path.


Chapter 8. Data maintenance

This chapter describes how to maintain your Tivoli Workload Scheduler databaseand other data files. The database is hosted on either the DB2 or Oracle RDBMSinfrastructure, as you determined when you installed it. You should use thedocumentation of DB2 or Oracle for general instructions on database maintenance.This chapter describes the maintenance activities that are specific to TivoliWorkload Scheduler.

It comprises the following sections:v “Maintaining the database”v “Maintaining the file system” on page 220v “Administrative tasks - DB2” on page 225v “Administrative tasks - Oracle” on page 231v “Migrating data from DB2 to Oracle and vice versa” on page 233v “Upgrading your database” on page 247v “Keeping track of database changes using audit reports” on page 263

Maintaining the databaseThis section discusses the following:v Backing up and restoring files in the Tivoli Workload Scheduler databases. See

“Backing up and restoring.”v Ensuring that a backup master domain manager is as up-to-date as possible. See

“Using a backup master domain manager with a backup database.”v Maintaining the performance level of the Tivoli Workload Scheduler databases.

See “Reorganizing the database” on page 219.

Backing up and restoringTo minimize downtime during disaster recovery, back up your master data filesfrequently to either offline storage or a backup master domain manager.

Backing up the database to offline storageRun a frequent backup of the database to offline storage. Follow the instructions inthe DB2 or Oracle documentation, as appropriate.

Tivoli Workload Scheduler is supplied with a utility that can be used for backup. Itis called tws_inst_pull_info. Its primary use is as a tool to gather Tivoli WorkloadScheduler information for IBM Software Support in the event of any problemsarising. However, it can equally be used as a backup tool. It backs up the database(DB2 only), the configuration files and the log files.

This tool is described in Tivoli Workload Scheduler: Troubleshooting Guide and givesfull details of what files are backed up, how to take a backup, and how to restorefrom one.

Using a backup master domain manager with a backup databaseSet up a backup master domain manager that accesses a different database thanthe master domain manager, and get your database administrator to set up amirror of the master domain manager's database onto the backup master domain


|

manager's database. In this way your backup master domain manager not onlyreceives copies of all the processing messages, as is provided for by the setting ofthe FullStatus attribute on the backup master domain manager, but is also able toaccess the mirrored database. The mirror frequency must be set high enough tomatch the frequency with which you change the database.

For more information about how to use a backup master domain manager, see“Changing a domain manager or dynamic domain manager” on page 269.

Backing up the configuration filesThe configuration files used by Tivoli Workload Scheduler are found in thefollowing places:

<TWA_home>/TWSFor the user options file, useropts.

<TWA_home>/TWS/*.*For the localopts, Sfinal, Security and *.msg files

<TWA_home>/TWS/mozart/*.*This directory contains the following files:

runmsgnoThis is used for the allocation of unique prompt numbers. On themaster domain manager this file should not be edited manually.On other workstations it can be edited only in the circumstancesdescribed in the Tivoli Workload Scheduler: Troubleshooting Guide.This file does not need to be backed up.

globaloptsThis is used to store a copy of three of the global properties storedin the database. If you have used versions of Tivoli WorkloadScheduler prior to version 8.3 you will probably remember that itwas an editable file that contained the global options. It is nolonger used for this purpose. It must be edited only in thecircumstances described in “Changing a master domain manager”on page 270. This file should be backed up if it is edited.

<TWA_home>/eWAS/profiles/TIPProfile/propertiesFor the application server configuration file, TWSConfig.properties

<TWA_home>/eWAS/profiles/TIPProfile/configThis contains the other configuration files for the embedded WebSphereApplication Server. Do not back them up manually. A utility to back themup is described in “Application server - configuration files backup andrestore” on page 307.

<TWA_home>/TWS/schedForecastFor forecast plan files.

<TWA_home>/TWS/schedlogFor archived plan files.

<TWA_home>/TWS/schedTrialFor trial plan files.

A detailed list of all files is not supplied, as there are too many files. Back up allthe files in these directories.


Note: The tws_inst_pull_info tool (described in the Tivoli Workload Scheduler:Troubleshooting Guide) is provided for sending information to support, butcan also be used to perform a backup of a DB2 database and some of theconfiguration files.

Backing up log filesMake a regular offline backup of all log files, identifying them from theinformation given in the section on log and trace files in the Tivoli WorkloadScheduler: Troubleshooting Guide.

If you use tws_inst_pull_info for backup (see the documentation in the sameguide), you do not need to separately backup these files.

Reorganizing the databaseThe database requires routine maintenance, as follows:

DB2 The DB2 database has been set up to maintain itself, so there is little usermaintenance to do. Periodically, DB2 checks the database by running aninternal routine. DB2 determines when this routine must be run using adefault policy. This policy can be modified, if need be, or can be switchedoff so that DB2 does not perform internal automatic maintenance. Usingthe statistical information that DB2 discovers by running this routine, itadjusts its internal processing parameters to maximize its performance.

This routine has also been made available for you to run manually in thecase either where you feel that the performance of DB2 has degraded, orbecause you have just added a large amount of data , and anticipateperformance problems. The routine is imbedded in a tool calleddbrunstats, which can be run to improve performance while DB2 isprocessing data without causing any interruption.

It is also possible to physically and logically reorganize the database usingthe dbreorg script. This effectively recreates the tablespace using its internalalgorithms to determine the best way to physically and logically organizethe tables and indexes on disk. This process is time-consuming, andrequires that Tivoli Workload Scheduler is down while it is run, but it doesprovide you with a freshly reorganized database after major changes.

The use of these tools is described in “Administrative tasks - DB2” on page225.

These tools are implementations of standard DB2 facilities. If you are anexpert user of DB2 you can use the standard facilities of DB2 to achievethe same results. For details go to the Information Center for DB2, version9.5, at: http://publib.boulder.ibm.com/infocenter/db2luw/v9r5//index.jsp.

Oracle For Oracle databases see the Oracle maintenance documentation.

Oracle 10g by default has an internally scheduled procedure to collectdatabase statistics: if the default schedule is not changed, Oracle 10g willautomatically optimize its performance by running this procedure daily.Oracle 9i does not have the same schedule by default, but could be set upto do so.

Chapter 8. Data maintenance 219

http://publib.boulder.ibm.com/infocenter/db2luw/v9r5/index.jsp


Maintaining the file systemSome of the file systems and directories need periodic maintenance. The details aregiven under the following topics:v “Avoiding full file systems”v “Log files and archived files” on page 223v “Temporary files” on page 225v “Managing event message queue file sizes” on page 225

Avoiding full file systemsPerhaps the most important maintenance task to perform is that of regularlycontrolling the file system or systems where Tivoli Workload Scheduler is installed,particularly on the master domain manager.

Tivoli Workload Scheduler has a number of files that can grow in size, either withmore extensive use, such as the Symphony file, or in the event of networkproblems, such as the message files. If the Symphony file, in particular, cannot beexpanded to contain all the required records, it might become corrupted. If thishappens on a fault-tolerant agent or on a domain manager other than the masterdomain manager, there is a recovery procedure (see the Tivoli Workload Scheduler:Troubleshooting Guide). If the Symphony file on the master domain manager iscorrupted, you have no alternative but to restart Tivoli Workload Scheduler, losingthe current plan's workload.

It is thus most important that you monitor the available space on the file system ofthe master domain manager where the Symphony file is generated, to ensure thatthere is always sufficient space for it to expand to cover any workload peaks, andalso that there is sufficient space for message files to expand in the event ofnetwork problems. Your experience with your workload and your network willguide you to determine what are the acceptable limits of available disk space.

The approximate size of the Symphony file can be estimated in advance. Itcontains items related both to the plan (see Table 46) and to the database (seeTable 47 on page 221). Estimate how many items you have in each category,multiply them by the indicated size in bytes, and sum them to find theapproximate Symphony file size:

Table 46. Algorithm for calculating the approximate size of the plan data in the Symphonyfile

Data in Symphony file from the current plan Bytes per instance

Per job stream instance: 512

Per job instance: 512

Per job "docommand" string > 40 bytes: The length of the"docommand" string

Per ad hoc prompt: 512

Per file dependency: 512

Per recovery prompt: 512

Per recovery job: 512


Table 47. Algorithm for calculating the approximate size of the database data in theSymphony file

Data in Symphony file from the database (on the masterdomain manager) Bytes per instance

Per workstation: 512

Per resource: 512

Per Windows user: 256

Per prompt: 512

If the global option ignoreCalendars is set to off, percalendar:

512

If you find that disk space is becoming too limited, and you cannot dynamicallyextend it, you must create a backup master domain manager with much morespace on its file system and then use the switchmgr command so that the backupbecomes your new domain manager. Instructions on how to do this for anydomain manager are given in “Changing a domain manager or dynamic domainmanager” on page 269, and in particular for a master domain manager, in“Changing a master domain manager” on page 270.

Monitoring the disk space used by Tivoli Workload SchedulerYou can use event-driven workload automation (EDWA) to monitor the disk spaceused by Tivoli Workload Scheduler and to start a predefined set of actions whenone or more specific events take place. You can use EDWA to monitor the useddisk space, to verify that there is enough space to generate the Symphony and logfiles, and to allow the product to work correctly. For more information aboutevent-driven workload automation, refer to Tivoli Workload Scheduler: User's Guideand Reference.

The following .XML file contains the definition of a sample event rule to monitorthe disk filling percentage. This event rule calls the MessageLogger action providerto write a message in a log file in an internal auditing database. If the conditiondescribed in the rule is already existing when you deploy the rule, the relatedevent is not generated. For more information about the MessageLogger actionprovider, refer to Tivoli Workload Scheduler: User's Guide and Reference::

<?xml version="1.0"?><eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules"xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/ruleshttp://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules/EventRules.xsd">

<eventRule name="FILESYSTEMFULL" ruleType="filter" isDraft="yes"><eventCondition name="twsDiskMonEvt1" eventProvider="TWSApplicationMonitor" eventType="TWSDiskMonitor"><scope>* Disk is filling up</scope><filteringPredicate><attributeFilter name="FillingPercentage" operator="ge"><value>filling_percentage</value></attributeFilter><attributeFilter name="Workstation" operator="eq"><value>workstation_name</value></attributeFilter><attributeFilter name="SampleInterval" operator="eq"><value>sample_interval</value>

</attributeFilter><attributeFilter name="MountPoint" operator="eq"><value>mount_point</value>

</attributeFilter>


</filteringPredicate></eventCondition><action actionProvider="MessageLogger" actionType="MSGLOG" responseType="onDetection"><scope>OBJECT=ADWDAD MESSAGE=Disk is filling up</scope><parameter name="ObjectKey"><value>object_key</value></parameter><parameter name="Severity"><value>message_severity</value>

</parameter><parameter name="Message"><value>log_message</value></parameter></action></eventRule>

where:

filling_percentageIs the filling percentage. Supported operators are as follows:

ge causes the event generation when the disk filling percentageincreases over the threshold value. The event is generated only thefirst time the specified disk filling percentage is reached. If yourestart the SSM agent and the filling percentage is higher than thethreshold value, the event is generated again. Table 48 provides anexample in which the ge operator is set to 70%.

Table 48. Example for the ge operator


Sample (0) >= 70% event not generated

Sample (0) < 70% event not generated

Sample (n-1) < 70% event not generated

Sample (n) >= 70% event generated

Sample (n+1) >= 70% event not generated

le causes the event generation when the disk filling percentagedecreases under the threshold value. The event is generated onlythe first time the specified disk filling percentage is reached. If yourestart the SSM agent and the filling percentage is lower than thethreshold value, the event is not generated until the fillingpercentage increases over the threshold value and then decreasesunder it again. Table 49 provides an example in which the leoperator is set to 50%:

Table 49. Example for the le operator


Sample (0) <= 50% event not generated

Sample (0) > 50% event not generated

Sample (n-1) > 50% event not generated

Sample (n) <= 50% event generated

Sample (n+1) <= 50% event not generated



sample_intervalIs the interval, expressed in seconds, for monitoring the disk fillingpercentage.

mount_pointIs the mount point of the file system where Tivoli Workload Scheduler isinstalled, for example: "C:" on Windows systems or "/" on UNIX systems.

object_keyIs a key identifying the object to which the message pertains.

message_severityIs the severity of the message.

log_messageIs the message to be logged.

Log files and archived filesLog files are produced from a variety of Tivoli Workload Scheduler activities.Other activities produce files which are archived after they have been used. Thedetails are given in Table 50:

Table 50. Log and trace file maintenance

Activity Description LocationMaintenancemethod

Process Each Tivoli Workload Schedulerprocess logs its activities, writingthem in log and trace messagefiles:

Log messages

These are messages intended foruse directly by you, and provideinformation, errors and warningsabout the processes.

netman<TWA_home>/TWS/stdlist/logs/<yyyymmdd>_NETMAN.log

Other processes<TWA_home>/TWS/stdlist/logs/<yyyymmdd>_TWSMERGE.log

This is the default situation. You can set anoption in the localopts file to createseparate log files for the major processes.

rmstdlist

Trace messages

These are messages written whena problem occurs that you canprobably not solve without theassistance of IBM SoftwareSupport.

netman<TWA_home>/TWS/stdlist/traces/<yyyymmdd>_NETMAN.log

Other processes<TWA_home>/TWS/stdlist/traces/<yyyymmdd>_TWSMERGE.log

This is the default situation. You can set anoption in the localopts file to createseparate trace files for the major processes.

Master domainmanager jobmanagement

The job manager process on themaster domain manager archivesthe previous period's Symphonyfile.

<TWA_home>/TWS/schedlog Manual


|||

Table 50. Log and trace file maintenance (continued)

Activity Description LocationMaintenancemethod

Job Each job that runs under TivoliWorkload Scheduler controlcreates an output file. These filesare archived.

<TWA_home>/TWS/stdlist/<date>

where <date> is in the format yyyy.mm.dd

rmstdlist

Forecast andtrial plancreation

The creation of forecast and trialplans writes to a log file. Trial <TWA_home>/TWS/schedTrial/*.log

Other processes<TWA_home>/TWS/schedForecast/*.log

Manual

Audit The audit facility writes log files. <TWA_home>/TWS/audit Manual

DB2 UDB DB2 logs its activities. Information about the location and viewingmethod for DB2 log files is supplied in theDB2 documentation. Go to the InformationCenter for DB2 (see Tivoli WorkloadAutomation: Publications for the link).

The main file to control is the db2diag.logfile, which is the most important DB2diagnostic file, which, without intervention,grows endlessly with no reuse of wastedspace. This does not apply, however, to thedatabase log files used by Tivoli WorkloadScheduler, which are set up for circularreuse of disk space, so they don't grow insize over a maximum value.

See the DB2documentation.

Oracle database Oracle logs its activities. See the Oracle documentation. See the Oracledocumentation.

The embeddedWebSphereApplicationServer

The application server writes logfiles

<TWA_home>/eWAS/profiles/TIPProfile/logs/

ffdcserver1

Manual

Netcool SSMmonitoringagent

The agent writes log files <TWA_home>/ssm/Log/ssmagent.logtraps.log

Manual

Other Other activities also write traceand log files.

<TWA_home>/TWS/methods Manual

The easiest method of controlling the growth of these directories is to decide howlong the log files are needed, then schedule a Tivoli Workload Scheduler job toremove any files older than the given number of days. Use the rmstdlistcommand for the process and job log files, and use a manual date check anddeletion routine for the others. Make sure that no processes are using these fileswhen you perform these activities.

See the Tivoli Workload Scheduler: User's Guide and Reference for full details of thermstdlist command.


Note: The rmstdlist command might give different results on different platformsfor the same scenario. This is because on UNIX platforms the command usesthe –mtime option of the find command, which is interpreted differently ondifferent UNIX platforms.

Temporary filesThe Tivoli Workload Scheduler master domain manager uses temporary files,located in <TWA_home>/TWS/tmp or /tmp and named TWS<XXXX>, when compiling newproduction control databases. These files are deleted when compiling is complete.

This directory also contains the Tivoli Workload Scheduler installation files and logfiles.

Managing event message queue file sizesThis publication contains the following information with respect to managingevent message queue file sizes:v See “Planning space for queues” on page 168 to learn about planning space for

message event queues (and also how to use evtsize to resize the queuesv See “Managing the event processor” on page 297 to learn about managing the

EIF event queuev See “Disk Space” on page 323 to learn about the impacts that increased fault

tolerance can have on message queuesv See “Workload spreading” on page 320 to learn about how to avoid bottlenecks

in the Mailbox.msg queue.

Administrative tasks - DB2This section describes how to perform some specific administrative tasks on DB2,as follows:v “Changing DB2 passwords”v “Locating the DB2 tools”v “User permissions for running the DB2 tools” on page 226v “Administering the DB2 maintenance feature” on page 226v “Reorganizing the DB2 database” on page 228v “Monitoring the lock list memory” on page 229

Changing DB2 passwords

To change passwords used by DB2 other than the <TWS_user> password or thepasswords of the user IDs used by Tivoli Workload Scheduler to access thedatabase (see “Changing key Tivoli Workload Scheduler passwords” on page 274)follow the instructions in the DB2 documentation; they do not directly impactTivoli Workload Scheduler.

Locating the DB2 tools

Tivoli Workload Scheduler is supplied with a small set of tools that you use toperform the following administrative tasks for DB2:v Run the DB2 statistics program, to maximize the performance of DB2

(dbrunstats). See “Running DB2 maintenance manually” on page 227 for a fulldescription of how to use the tool.


v Reorganize the database (dbreorg). See “Reorganizing the DB2 database” onpage 228 for a full description of how to use the tool.

Find these tools in the following directory:<TWA_home>/TWS/dbtools/db2/scripts

Note: The tools in this directory include some that are for the use of IBM SoftwareSupport:

dbcatalogdbsetup

Do not run these scripts. To do so might damage or overwrite the data in yourdatabase.

User permissions for running the DB2 toolsThe DB2 tools must be run by a user who has the following permissions:v DB2 administrator permissions – the user must be defined to DB2 as a DB2

Administratorv Full access (777) to the Tivoli Workload Scheduler installation directory

Administering the DB2 maintenance featureAt installation, DB2 automatic maintenance is switched on, which means that DB2periodically checks to see if it needs to collect new database statistics, so that it canperform the maintenance, adjusting the performance parameters to maximizeperformance.

This section describes how to administer the automatic maintenance, by changinghow and when it is run, switching it off and on again, and running it manually.See the following:v “Modifying the DB2 automatic maintenance policy”v “Switching off automatic maintenance”v “Switching on automatic maintenance” on page 227v “Running DB2 maintenance manually” on page 227

Modifying the DB2 automatic maintenance policyTo know when and how the statistics used by the automatic maintenance must becollected, DB2 uses a default policy, which can be customized. The procedure is asfollows:1. Right-click the database in the DB2 Control Center and select Configure

Automatic Maintenance from the context menu.2. Follow the instructions in the wizard, modifying any of the default policy

parameters that you think might improve the way DB2 chooses when to runthe automatic maintenance.

Switching off automatic maintenanceIf you want to take full manual control of the database, switch off the automaticmaintenance as follows:1. Check that the user who is going to run the procedure has the appropriate

rights (see “User permissions for running the DB2 tools”)2. On the DB2 server computer, open a DB2 shell, as follows:

UNIX Follow these steps:


a. Issue the command su - db2inst1, or change to the subdirectorysqllib of the home directory of the owner of the DB2 instance (bydefault db2inst1)

b. Launch the command . ./db2profile

WindowsSelect from the Start menu, Programs → IBM DB2 → Command LineTools → Command Window

3. Check that the command shell is correctly initialized by issuing the commanddb2, and checking that the command is recognized.

4. Issue the command quit to leave the DB2 Processor mode.5. Issue the following command:

db2 UPDATE DB CFG FOR <database_name> USING AUTO_MAINT OFF

where <database_name> is the name of the Tivoli Workload Scheduler database(the installed default name is TWS; supply this value unless you have changedit).

6. To make the changes effective, either disconnect and reconnect all the DB2clients, or restart the DB2 instance (using db2stop and db2start).

Switching on automatic maintenanceTo switch the automatic maintenance back on again, do as follows:1. Check that the user who is going to run the procedure has the appropriate

rights (see “User permissions for running the DB2 tools” on page 226)2. On the DB2 server computer, open a DB2 shell, as follows:

UNIX Follow these steps:a. Issue the command su - db2inst1, or change to the subdirectory

sqllib of the home directory of the owner of the DB2 instance (bydefault db2inst1)




4. Issue the command quit to leave the DB2 Processor mode.5. Issue the following command:

db2 UPDATE DB CFG FOR <database_name> USING AUTO_MAINT ON

where <database_name> is the name of the Tivoli Workload Scheduler database(the installed default name is TWS; supply this value unless you have changedit).

6. To make the changes effective, either disconnect and reconnect all the DB2clients, or restart the DB2 instance (using db2stop and db2start).

Running DB2 maintenance manuallyThis section describes how to perform the DB2 maintenance process on demand,instead of waiting for DB2 to do it according to its automatic maintenance policy.The process is run by the tool dbrunstats which you can run whenever you needto, without stopping DB2 or interrupting its processing.

To run this tool, follow this procedure:1. Locate the DB2 tools: see “Locating the DB2 tools” on page 225.


2. Check that the user who is going to run the procedure has the appropriaterights (see “User permissions for running the DB2 tools” on page 226)

3. Open a DB2 shell, as follows:






5. Issue the command quit to leave the DB2 Processor mode.6. From within the shell, change to the directory <TWA_home>/TWS/dbtools/db2/

scripts

7. Run the script:

UNIX dbrunstats.sh database [user [password]]

Windowsdbrunstats database [user [password]]

where:

databaseThe name of the database:v If you are running this from the computer where the DB2 server is

installed, the installed default name is TWS. Supply this value unlessyou have changed it.

v If you are running this from the computer where the DB2 client isinstalled, the installed default name is TWS_DB. Supply this valueunless you have changed it.

user The DB2 administration user. If this is omitted the ID of the userrunning the command will be used.

passwordThe password of the DB2 administration user. If this is omitted it willbe requested interactively.

The script runs, giving you various messages denoting its progress andsuccessful conclusion. At the end (it is not particularly time-consuming) thedatabase performance parameters have been reset to maximize performance.

Reorganizing the DB2 database

Using this tool, the database physically reorganizes the data tables and indexes,optimizing disk space usage and ease of data access. The process istime-consuming, requires that the database is backed up, and that Tivoli WorkloadScheduler is stopped. However, at the end you have a database that is completelyreorganized.

To reorganize the database follow this procedure:1. Back up the Tivoli Workload Scheduler database. Use the method described in

“Backing up the database to offline storage” on page 217.


2. Stop all Tivoli Workload Scheduler processes. See “Unlinking and stoppingTivoli Workload Scheduler” on page 283 for full details.

3. Check that the user who is going to run the procedure has the appropriaterights (see “User permissions for running the DB2 tools” on page 226)

4. Open a DB2 shell, as follows:






6. Issue the command quit to leave the DB2 Processor mode.7. From within the shell, change to the directory <TWA_home>/TWS/dbtools/db2/

scripts

8. Run the script:

UNIX dbreorg.sh database [user [password]]

Windowsdbreorg database [user [password]]

where:

databaseThe name of the database:v If you are running this from the computer where the DB2 server is


v If you are running this from the computer where the DB2 client isinstalled, the installed default name is TWS_DB. Supply this valueunless you have changed it.

user The DB2 administration user. If this is omitted the ID of the userrunning the command will be used.

passwordThe password of the DB2 administration user. If this is omitted it willbe requested interactively.

The script runs, giving you various messages denoting its progress andsuccessful conclusion.

9. Restart Tivoli Workload Scheduler.

Monitoring the lock list memory

If the memory that DB2 allocates for its lock list begins to be fully used, DB2 canbe forced into a "lock escalation", where it starts to lock whole tables instead of justindividual table rows, and increasing the risk of getting into a deadlock.

This happens especially when there are long transactions, such as the creation orextension of a plan (production, trial, or forecast).


To avoid this problem occurring, set the automatic notification in the DB2 HealthCenter, so that you can be advised of any lock list problems building up.

However, if you think that deadlock situations have been occurring, follow thisprocedure to verify:1. With the WebSphere Application Server active, log on as DB2 administrator to

the DB2 server, for example,su - db2inst1

2. Run the following command to determine where the Tivoli WorkloadScheduler database is located:db2 list active databases

The output might be as follows:Database name = TWSApplications connected currently = 2Database path = /home/db2inst1/db2inst1/NODE0000/SQL00002/

3. Run:cd <Database path>/db2event/db2detaildeadlock

4. Connect to the Tivoli Workload Scheduler database, for example:db2 connect to TWS

5. Flush the event monitor that watches over deadlocks (active by default) withthe following:db2 flush event monitor db2detaildeadlock

6. Disconnect from the database with:db2 terminate

7. Obtain the event monitor output with:db2evmon -path . > deadlock.out

The file deadlock.out now contains the complete deadlock history since theprevious flush operation.

8. To find out if there have been deadlocks and when they occurred, run:grep "Deadlock detection time" deadlock.out

The output might be as follows:Deadlock detection time: 11/07/2008 13:02:10.494600Deadlock detection time: 11/07/2008 14:55:52.369623

9. But the fact that a deadlock occurred does not necessarily mean that the locklist memory is inadequate. For that you need to establish a relationship withlock escalation. To find out if there have been lock escalation incidents prior todeadlocks, run:grep "Requesting lock as part of escalation: TRUE" deadlock.out

The output might be as follows:Requesting lock as part of escalation: TRUERequesting lock as part of escalation: TRUE

If there has been lock escalation related to deadlocks, it is a good idea tomodify the values of the following parameters.

LOCKLISTThis configures, in 4KB pages, the amount of memory allocated tolocking management


MAXLOCKSThis configures the percentage of the memory that a single transactioncan use, above which DB2 escalates, even though the memory mightnot be full

10. To determine the values currently being applied to the Tivoli WorkloadScheduler database, do the following:db2 get db cfg for TWS | grep LOCK

The output might be as follows:Max storage for lock list (4KB) (LOCKLIST) = 8192Percent. of lock lists per application (MAXLOCKS) = 60Lock timeout (sec) (LOCKTIMEOUT) = 180

The example shows the typical output for the Tivoli Workload Schedulerdatabase if no modification has taken place to these values:v "8192" = 4KB x 8192 pages = 32 MB of memoryv "60" = 60% – the percentage of memory that a single transaction can occupy

before triggering an escalationv "180" = 3 minutes of timeout for the period a transaction can wait to obtain

a lock11. The most straightforward action to take is to double the amount of memory to

64MB, which you do with the command:db2 update db cfg for TWS using LOCKLIST 16384 immediate

12. Alternatively, you can set DB2 to automatically modify the LOCKLIST andMAXLOCKS parameters according to the amount of escalation beingexperienced and the available system memory. This self-tuning is a slowprocess, but adapts the database to the needs of the data and the availablesystem configuration. It is done by setting the values of these parameters toAUTOMATIC, as follows:db2 update db cfg for TWS using LOCKLIST AUTOMATIC immediate

DB2 responds with messages telling you that MAXLOCKS has also been set toAUTOMATIC:SQL5146W "MAXLOCKS" must be set to "AUTOMATIC" when "LOCKLIST" is"AUTOMATIC".

"MAXLOCKS" has been set to "AUTOMATIC"

Note: The self-tuning facility is only available from V9.1 of DB2.

Administrative tasks - OracleThis section describes how to perform some specific administrative tasks for theOracle database.v “Changing the Oracle access password” on page 232v “Locating the Oracle tools” on page 232v “Maintaining the Oracle database” on page 232v “Obtaining information about the Tivoli Workload Scheduler databases installed

on an Oracle instance” on page 232v “User permissions for running the Oracle tools” on page 233v “Changing the Oracle host name, port, or database name” on page 291


Changing the Oracle access password

This is described as part of the process of changing the password for a masterdomain manager or backup master domain manager. See “Changing key TivoliWorkload Scheduler passwords” on page 274.

Locating the Oracle tools

Tivoli Workload Scheduler is supplied with a small set of tools that you use toperform the following administrative tasks for Oracle:v Grant the user permissions for the Dynamic Workload Console views (dbgrant).

See the Dynamic Workload Console online help for full details.v Migrating from DB2 to Oracle or vice versa (prepareSQLScripts,

createdb_root_ora, updateSetupCmdLine ). See “Migrating data from DB2 toOracle and vice versa” on page 233 for full details.

Locate these tools in the following directory:<TWA_home>/TWS/dbtools/oracle/scripts

Note: The directory also includes some scripts that are only for the use of IBMSoftware Support:

dbmigratedbpartitiondbsetupdbupgradelaunchdb_root_ora_migratedb_root_ora

Do not run these scripts. To do so might damage or overwrite the data in yourdatabase.

Maintaining the Oracle databaseLike DB2, Oracle has a routine that regularly maintains the database. Similarly, thistoo can be run manually. The tool is invoked as follows:dbms_stats.gather_schema_stats<schema_owner>

See the Oracle documentation for full details of how and when to run it.

Obtaining information about the Tivoli Workload Schedulerdatabases installed on an Oracle instance

To determine which Tivoli Workload Scheduler databases are installed on anOracle instance, do the following:su - oracle (UNIX only)sqlplus system/<system_password>@<service_name>SQL> select * from all_tws_schemas;

The output should look like the following:SCHEMA_NAME------------------------------MDLmdm85TWS_user


Note:

1. More than one instance of Tivoli Workload Scheduler can be shared inone instance of Oracle, using different schemas.

2. In Oracle, the concept of "schema" and "user" are the same, so droppingan Oracle schema means dropping an Oracle user, which you do asfollows:SQL> drop user MDL cascade;

User permissions for running the Oracle toolsThe Oracle tools must be run by a user who has the following permissions:v Oracle administrator permissions – the user must be defined to Oracle as an

administratorv Full access (777) to the Tivoli Workload Scheduler installation directory

Migrating data from DB2 to Oracle and vice versaThis section applies to Tivoli Workload Scheduler master domain managers andbackup masters. It documents how to migrate the Tivoli Workload Scheduler datafrom one RDBMS to another.

There are two ways to accomplish the migration. You can use either way tomigrate your data from DB2 to Oracle or vice versa.

Parallel data migrationThe migration is between two instances of Tivoli Workload Scheduler, onethat uses DB2 while the other uses Oracle

ReconfigurationThe database is migrated from one RDBMS support mechanism to another,and Tivoli Workload Scheduler instance is re-configured to point to adifferent database without installing another instance.

Note: Neither of these procedures migrate the following information from thesource database:v The pre-production planv The history of job runs and job statisticsv The state of running event rule instances. This means that any complex

event rules, where part of the rule has been satisfied prior to the databasemigration, are generated after the migration as new rules. Even if thesubsequent conditions of the event rule are satisfied, the record that thefirst part of the rule was satisfied is no longer available, so the rule willnever be completely satisfied.

The following sections describe the migration procedures.v “Parallel data migration from DB2 to Oracle” on page 234v “Parallel data migration from Oracle to DB2” on page 235v “Reconfiguration from DB2 to Oracle” on page 237v “Reconfiguration from Oracle to DB2” on page 242


Parallel data migration from DB2 to Oracle

With the following steps all scheduling object definitions and global options can bemigrated from the DB2 database of a Tivoli Workload Scheduler version 8.5instance to the Oracle database of another instance.1. Fresh-install another instance of a Tivoli Workload Scheduler version 8.5 master

domain manager and make it point to an Oracle database.2. Use composer, the Dynamic Workload Console to define this instance as a

fault-tolerant agent in the database of the current master domain manager thatpoints to DB2.

3. On the master domain manager that points to DB2 run the dataexportcommand or script to export all scheduling object definitions and globaloptions from DB2. Find this file in the bin subdirectory of the Tivoli WorkloadScheduler home directory.Run dataexport from a Windows or UNIX command prompt as follows:dataexport <source_dir> <export_dir>

where:

source_dirThe installation directory of the instance of Tivoli Workload Schedulerversion 8.5 that points to the DB2 database.

export_dirThe directory where the export files are to be created.

For example:dataexport.cmd F:\TWS85\twsDB2user F:\TWS85\export

The object definitions and the global options are retrieved from the DB2database and placed in the F:\TWS85\export directory.

4. Verify the following files were created in export_dir:v calendars.defv jobs.def

Note: The record length supported by DB2 is 4095 characters, but itdecreases to 4000 characters with Oracle. When you migrate your jobdefinitions to Oracle, any job scripts or commands exceeding 4000characters in length are not migrated. In such case, the data importutility replaces the job definition with a dummy job definition and setsthe job priority to 0, guaranteeing that successors are not run.

v globalOpts.defv erules.defv parms.defv prompts.defv resources.defv scheds.defv topology.defv users.def (includes encrypted user passwords)

5. On the master domain manager that points to DB2 do the following:a. Ensure that the carry forward option is set to ALL. Run:

optman chg cf=ALLb. Add the new instance (that you installed in step 1 and that you

momentarily defined as a fault-tolerant agent) in the current plan. To dothis, run:


JnextPlan -for 0000c. Check that the new instance was linked by running:

conman sc

6. On the new instance run the dataimport command or script to import allscheduling object definitions and global options to the Oracle database. Findthis file in the bin subdirectory of the Tivoli Workload Scheduler homedirectory.Run dataimport from a Windows or UNIX command prompt as follows:dataimport <source_dir> <export_dir>

where:

source_dirThe installation directory of the new instance of Tivoli WorkloadScheduler version 8.5 pointing to the Oracle database.

export_dirThe directory from where the export files are to be read from. Thisdirectory is the same export_dir directory specified for dataexport.

For example:dataimport.cmd F:\TWS85\twsORACLEuser F:\TWS85\export

The object definitions and the global options are retrieved from theF:\TWS85\export directory and stored in the Oracle database.

7. On the master domain manager that points to DB2 run the conman switchmgrcommand to make the Tivoli Workload Scheduler instance pointing to Oracle asthe acting master domain manager. For information on this command seeUser's Guide and Reference.

You have now completed the data migration steps.

Parallel data migration from Oracle to DB2

With the following steps all scheduling object definitions and global options can bemigrated from the Oracle database of a Tivoli Workload Scheduler version 8.5instance to the DB2 database of another instance (freshly installed or upgraded toversion 8.5).1. On the current master domain manager pointing to the Oracle database run the

dataexport command or script to export all scheduling object definitions andglobal options. Find this file in the bin subdirectory of the Tivoli WorkloadScheduler home directory.Run dataexport from a Windows or UNIX command prompt as follows:dataexport <source_dir> <export_dir>

where:

source_dirThe installation directory of the instance of Tivoli Workload Schedulerthat points to the Oracle database.


For example:dataexport.cmd F:\TWS85\twsORACLEuser F:\TWS85\export


The object definitions and the global options are retrieved from the Oracledatabase and placed in the F:\TWS85\export directory.

2. Verify the following files were created in export_dir:v calendars.defv erules.defv jobs.defv globalOpts.defv parms.defv prompts.defv resources.defv scheds.defv topology.defv users.def (includes encrypted user passwords)

3. Fresh-install another instance of Tivoli Workload Scheduler version 8.5 orupgrade an existing instance to version 8.5 making it point to a DB2 database.

4. Use composer or the Dynamic Workload Console to define this instance as afault-tolerant agent in the database of the master domain manager that pointsto Oracle.

5. On the current master domain manager that points to Oracle do the following:a. Ensure that the carry forward option is set to ALL. Run:

optman chg cf=ALLb. Add the new instance (that you installed in step 3 and that you

momentarily defined as a fault-tolerant agent) in the current plan. To dothis, run:JnextPlan -for 0000

c. Check that the new instance was linked by running:conman sc

6. On the new instance run the dataimport command or script to import allscheduling object definitions and global options to DB2. Find this file in the binsubdirectory of the Tivoli Workload Scheduler home directory.Run dataimport from a Windows or UNIX command prompt as follows:dataimport <source_dir> <export_dir>

where:

source_dirThe installation directory of the instance of Tivoli Workload Schedulerthat points to the DB2 database.


For example:dataimport.cmd F:\TWS85\twsDB2user F:\TWS85\export

The object definitions and the global options are retrieved from theF:\TWS85\export directory and stored in the DB2 database.

7. On the master domain manager that points to Oracle run the conman switchmgrcommand to make the Tivoli Workload Scheduler instance pointing to DB2 asthe acting master domain manager. For information on the switchmgrcommandsee User's Guide and Reference.

You have now completed the data migration steps.


Reconfiguration from DB2 to Oracle

With the following steps all scheduling object definitions and global options can bemigrated from the DB2 database of a Tivoli Workload Scheduler version 8.5 masterdomain manager and made to point to an Oracle database.1. Run the dataexport command or script to export all scheduling object

definitions and global options from DB2. Find this file in the bin subdirectoryof the Tivoli Workload Scheduler version 8.5 home directory.Run dataexport from a Windows or UNIX command prompt as follows:dataexport <source_dir> <export_dir>

where:

source_dirThe Tivoli Workload Scheduler version 8.5 installation directory.


For example:dataexport.cmd F:\TWS85\tws85user F:\TWS85\tws85user\export

The object definitions and the global options are retrieved from the DB2database and placed in the F:\TWS85\tws85user\export directory.


3. Stop the WebSphere Application Server using the conman stopappservercommand (see “Starting and stopping the application server andappservman” on page 303)

4. Run prepareSQLScripts.bat (.sh) to customize the SQL scripts with theparameters needed to create the Tivoli Workload Scheduler schema in theOracle database. Find this file in the TWA_home/TWS/dbtools/oracle/scriptsdirectory.Run prepareSQLScripts from a Windows or UNIX command prompt asfollows:v From a UNIX shell run:

prepareSQLScripts-dbRoot <dbRoot>-dbName <dbName>-twsDbUser <twsDbUser>-twsDbPassword <twsDbUser_password>[-tempDir <tempDir>][-dataTablespace <dataTablespace_name>][-logTablespace <logTablespace_name>]


[–tempTablespace <tempTablespace_name>][-companyName <companyName>][-masterDmName <masterDmName>][-eifPort <eifPort>]

v From a Windows command prompt run:cmd /K prepareSQLScripts

-dbRoot <dbRoot>-dbName <dbName>-twsDbUser <twsDbUser>-twsDbPassword <twsDbUser_password>[-tempDir <tempDir>][-dataTablespace <dataTablespace_name>][-logTablespace <logTablespace_name>][–tempTablespace <tempTablespace_name>][-companyName <companyName>][-masterDmName <masterDmName>][-eifPort <eifPort>]

where:

dbRootThe path where the RDBMS software is installed - the Oracle homedirectory.

dbNameThe name of the database.

twsDbUserThe database user for Tivoli Workload Scheduler.

twsDbPasswordThe password of this user.

tempDirThe directory where the temporary files created by this process areplaced. On Windows the default is <drive>\Documents andSettings\<current_user>\Local Settings\Temp.

dataTablespaceThe name of the table space for the Tivoli Workload Scheduler data.The default is USERS. If you provided a different value at installationtime, enter that value again.

logTablespaceThe name of the table space for the Tivoli Workload Scheduler log.The default is USERS. If you provided a different value at installationtime, enter that value again.

tempTablespaceThe name of the table space for temporary data. The default is TEMP. Ifyou provided a different value at installation time, enter that valueagain.

companyNameThe name of your company. The default is MYCOMPANY. If you provideda different value at installation time, enter that value again.

masterDmNameThe name of the master domain. The default is MASTERDM. If youprovided a different value at installation time, enter that value again.

eifPortThe EIF port. The default is 31123. If you provided a different value atinstallation time, enter that value again.


For example:cmd /K prepareSQLScripts.bat -dbRoot D:\Oracle

-dbName TWS-twsDbUser tws85User-twsDbPassword mypassw0rd

The SQL scripts are customized to create an Oracle schema named tws85useron the TWS database. The names of the table spaces are the defaults: USERS andTEMP.

5. Run createdb_root.bat (.sh) to create the database and schema followingthe specifications of the previous step. Find this file in thetempDir/TWA/tws85/scripts directory, where tempDir is the parameter youspecified in step 4 on page 237.Run createdb_root as follows:v From a UNIX shell, run:

createdb_root<netService><oracleAdmin><oracleAdminPassword><twsDbUser><twsDbPassword><isBackupManager><isPartitioned>

v From a Windows command prompt, run:cmd /K createdb_root

<netService><oracleAdmin><oracleAdminPassword><twsDbUser><twsDbPassword><isBackupManager><isPartitioned>

where:

netServiceThe net service name required to connect to the Oracle database.

oracleAdminThe user ID of the Oracle database administrator.

oracleAdminPasswordThe password for oracleAdmin.

twsDbUserThe owner of the Tivoli Workload Scheduler schema that youspecified also in step 4 on page 237.

twsDbPasswordThe password for twsDbUser that you specified also in step 4 on page237.

isBackupManagerSpecify TRUE if you are migrating a backup master domain manager.Specify FALSE otherwise.

isPartitionedSpecify TRUE if the Oracle Partitioning feature is enabled for thedatabase. Specify FALSE otherwise.

For example:createdb_root TWS SYSTEM passw1rd tws85user passw0rd FALSE TRUE


creates a database schema named tws85user on the TWS database.If something goes wrong and you have to rerun this step after finding (andfixing) the error, you must first log in to the database as the administrator anddrop the twsDbUser (tws85user in the example).

6. Change the data source properties from DB2 to Oracle using thechangeDataSource.bat (.sh) command or script to switch the data source inWebSphere Application Server from DB2 to Oracle.See “Changing data source properties” on page 286 for details on how to usethe command.a. Clear the values of the following properties:

DB2Type4JndiNameDB2Type4DatabaseNameDB2Type4ServerNameDB2Type4PortNumber

Note: For the property DB2Type4JndiName replace the value with anycharacter or string to nullify it.

b. Set these properties to the following values:OracleType2JndiName=jdbc/twsdbOracleType2DatabaseName=the Oracle instance nameOracleType2PortNumber=the Oracle listener port number

c. Set the JDBC driver path for the Oracle database toORACLE_JDBC_DRIVER_PATH=Oracle_home/jdbc/lib and the Oracle instancetype and name to ORACLETYPE2URL=JDBC:ORACLE:OCI:@instance_name

7. Use the changeSecurityProperties.bat (.sh) command or script to changethe following security settings (see “Changing the security settings” on page296 for details on using the command):

j2cUseridWrite the value you used for twsDbUser in prepareSQLScripts.

j2cPasswordWrite the password for the twsDbUser.

Note: After you updated these two values, make sure that you also erase allthe other lines in the security properties file before you export it againwith the changeSecurityProperties command. Failure to do so willresult in all the passwords contained in the file being saved as stringsof asterisks (*).

8. Modify the TWSConfig.properties file located in the TWA_home/eWAS/profiles/TIPProfile/properties directory. Take the comment marks off the followinglines and edit them as shown:com.ibm.tws.dao.rdbms.rdbmsName = Oraclecom.ibm.tws.dao.rdbms.modelSchema = <twsDbUser>com.ibm.tws.dao.rdbms.eventRuleSchema=<twsDbUser>com.ibm.tws.dao.rdbms.logSchema=<twsDbUser>

where twsDbUser is the owner of the Tivoli Workload Scheduler schema thatyou specified also in the previous steps.

9. For UNIX only: run the updateSetupCmdLine.sh command or script to set thepaths for the new database in the WebSphere Application Server profile.Locate this script in the <TWA_home>/TWS/dbtools/oracle/scripts directory.The syntax is as follows:updateSetupCmdLine.sh -installRoot <TWA_home> -dbRoot <DB_home>


where:

–installRoot <TWA_home>The installation directory of Tivoli Workload Scheduler.

–dbRoot <DB_home>The installation directory of the database.


11. Manually copy the master domain manager definition from the topology.deffile you exported in step 1 on page 237 (you can find it in export_dir) anduse composer new to add it in the Oracle database.

12. Run dataimport to import all scheduling object definitions and global optionsto the Oracle database. Find this file in the bin subdirectory of the TivoliWorkload Scheduler home directory.Run dataimport from a Windows or UNIX command prompt as follows:dataimport source_dir export_dir

where:

source_dirThe Tivoli Workload Scheduler installation directory.


For example:dataimport.cmd F:\TWS85\tws85user F:\TWS85\tws85user\export

The object definitions and the global options are retrieved from theF:\TWS85\tws85user\export directory and stored in the new Oracle database.

13. Run the following command to set the carry forward option to ALL:optman chg cf=ALL

14. Update the Symphony file by creating a plan with 0 extension period thatbegins at the end of the current plan:JnextPlan -from start_time -for 0000

where start_time is the date and time when the current plan ends.

You have now completed the reconfiguration steps.

To migrate a backup master domain manager, perform the following steps:v Stop the WebSphere Application Server using the conman stopappserver

command (see “Starting and stopping the application server and appservman”on page 303)

v Run steps 6 on page 240, 7 on page 240, 9 on page 240v Start the WebSphere Application Server using the conman startappserver


v Set the isBackupManager parameter of the createdb_root command (script) toTRUE.


Reconfiguration from Oracle to DB2

With the following steps all scheduling object definitions and global options can bemigrated from the Oracle database of a Tivoli Workload Scheduler version 8.5master domain manager and made to point to a DB2 database.1. Run the dataexport command or script to export all scheduling object

definitions and global options from Oracle. Find this file in the binsubdirectory of the Tivoli Workload Scheduler version 8.5 home directory.Run dataexport from a Windows or UNIX command prompt as follows:dataexport <source_dir> <export_dir>

where:

source_dirThe Tivoli Workload Scheduler version 8.5 installation directory.


For example:dataexport.cmd F:\TWS85\tws85user F:\TWS85\tws85user\export

The object definitions and the global options are retrieved from the Oracledatabase and placed in the F:\TWS85\tws85user\export directory.


3. Stop WebSphere Application Server as described in “Application server -starting and stopping” on page 300.

4. Run prepareSQLScripts.bat (.sh) to customize the SQL scripts with theparameters needed to create the Tivoli Workload Scheduler database in DB2.Find this file in the TWA_home/TWS/dbtools/db2/scripts directory.Run prepareSQLScripts from a Windows or UNIX command prompt asfollows:v From a UNIX shell run:

prepareSQLScripts-dbRoot <dbRoot>-dbName <dbName>-dbLocalAdmin <dbLocalAdmin>-twsDbUser <twsDbUser>[-tempDir <tempDir>][-dataTablespace <dataTablespace_name>][-dataTablespacePath <dataTablespacePath>][-logTablespace <logTablespace_name>][-logTablespacePath <logTablespacePath>][–tempTablespace <tempTablespace_name>]


[–userTempTablespace <userTempTablespace_name>][-companyName <companyName>][-masterDmName <masterDmName>][-eifPort <eifPort>]

v From a Windows command prompt run:cmd /K prepareSQLScripts

-dbRoot <dbRoot>-dbName <dbName>-dbLocalAdmin <dbLocalAdmin>-twsDbUser <twsDbUser>[-tempDir <tempDir>][-dataTablespace <dataTablespace_name>][-dataTablespacePath <dataTablespacePath>][-logTablespace <logTablespace_name>][-logTablespacePath <logTablespacePath>][–tempTablespace <tempTablespace_name>][–userTempTablespace <userTempTablespace_name>][-companyName <companyName>][-masterDmName <masterDmName>][-eifPort <eifPort>]

where:

dbRootThe path where the RDBMS software is installed.

dbNameThe name of the database.

dbLocalAdminThe user ID of the local database administrator.

twsDbUserThe database user for Tivoli Workload Scheduler.

tempDirThe directory where the temporary files created by this process areplaced. On Windows the default is <drive>\Documents andSettings\<current_user>\Local Settings\Temp.

dataTablespaceThe name of the table space for the Tivoli Workload Scheduler data.The default is TWSDATA. If you provided a different value at installationtime, enter that value again.

dataTablespacePathThe path of the table space for the Tivoli Workload Scheduler data.

logTablespaceThe name of the table space for the Tivoli Workload Scheduler log.The default is TWSLOG. If you provided a different value at installationtime, enter that value again.

logTablespacePathThe path of the table space for the Tivoli Workload Scheduler log files.

tempTablespaceThe name of the table space for temporary data. The default is TEMP. Ifyou provided a different value at installation time, enter that valueagain.


userTempTablespaceThe name of the table space for temporary user data. The default isUSERTEMP. If you provided a different value at installation time, enterthat value again.

companyNameThe name of your company. The default is MYCOMPANY. If you provideda different value at installation time, enter that value again.

masterDmNameThe name of the master domain. The default is MASTERDM. If youprovided a different value at installation time, enter that value again.

eifPortThe EIF port. The default is 31123. If you provided a different value atinstallation time, enter that value again.

For example:cmd /K prepareSQLScripts.bat -dbRoot D:\DB2

-dbName TWS-dbLocalAdmin db2admin-twsDbUser tws85User

The SQL scripts are customized to create a database named TWS in DB2 foruser tws85user. The names of the table spaces are the defaults: TWSDATA,TWSLOG, TEMP and USERTEMP.

5. Run createdb_root.bat (.sh) to create the database following thespecifications of the previous step. Find this file in the tempDir/TWA/tws85/scripts directory, where tempDir is the parameter you specified in step 4 onpage 242.Run createdb_root as follows:v From a UNIX shell, run:

createdb_root<dbName><isClientInstallation><dbNodeName><hostName><srvPortNumber><db2Admin><db2AdminPwd><instanceName><isBackupManager>

v From a Windows command prompt, run:cmd /K createdb_root

<dbName><isClientInstallation><dbNodeName><hostName><srvPortNumber><db2Admin><db2AdminPwd><instanceName><isBackupManager>

where:

dbNameThe name of the DB2 database. The maximum length is 5 characters.

isClientInstallationThe value is:v TRUE if the database is a DB2 client.


v FALSE if the database is a DB2 server.

dbNodeNameThe name of the DB2 node.

hostNameThe host name of the computer where DB2 is to be installed.

srvPortNumberThe TCP/IP port number used to communicate with the DB2 server.The default is 50000.

db2AdminThe user ID of the DB2 administrator.

db2AdminPwdThe password for db2Admin.

instanceNameThe name of the DB2 server instance.

isBackupManagerSpecify TRUE if you are migrating a backup master domain manager.Specify FALSE otherwise.

For example:createdb_root TWS FALSE TWS_ND myhost 50000 db2admin passw1rd DB2 FALSE

creates a database named TWS on a DB2 server instance named DB2.6. Use the changeDataSource.bat (.sh) command or script to switch the data

source in WebSphere Application Server from Oracle to DB2.See “Changing data source properties” on page 286 for details on how to usethe command.a. Clear the following properties:

OracleType2JndiNameOracleType2DatabaseNameOracleType2ServerNameOracleType2PortNumber

b. Set the following properties:DB2Type4JndiNameDB2Type4DatabaseNameDB2Type4ServerNameDB2Type4PortNumber

c. Set the JDBC driver path for the DB2 in both DB2_JDBC_DRIVER_PATH andDB2UNIVERSAL_JDBC_DRIVER_PATH (the path is the same for both properties).

7. Reset to a name of your choice the ...JndiName property of the RDBMS fromwhich you are changing.

8. Set to jdbc/twsdb the ...JndiName property of the new RDBMSv See that the following properties are set:

– For DB2:DB2Type4JndiNameDB2Type4DatabaseNameDB2Type4ServerNameDB2Type4PortNumber

9. Run the changeSecurityProperties.bat (.sh) command or script to changethe following security settings:

j2cUseridWrite the value you used for twsDbUser in prepareSQLScripts.


j2cPasswordWrite the password for twsDbUser.

Note: After you updated these two values, make sure that you also erase allthe other lines in the security properties file before you export it againwith the changeSecurityProperties command. Failure to do so willresult in all the passwords contained in the file being saved as stringsof asterisks (*).

See “Changing the security settings” on page 296 for details.10. Modify the TWSConfig.properties file located in the TWA_home/eWAS/profiles/

TIPProfile/properties directory. Comment the following four lines:com.ibm.tws.dao.rdbms.rdbmsName = Oraclecom.ibm.tws.dao.rdbms.modelSchema = <twsDbUser>com.ibm.tws.dao.rdbms.eventRuleSchemacom.ibm.tws.dao.rdbms.logSchema

where twsDbUser is the owner of the Tivoli Workload Scheduler Oracleschema.

11. For UNIX only: run the updateSetupCmdLine.sh command or script to set thepaths for the new database. Locate this script in the <TWA_home>/TWS/dbtools/db2/scripts directory. The syntax is as follows:updateSetupCmdLine.sh -installRoot <TWA_home> -dbRoot <DB_home>

where:

–installRoot <TWA_home>The installation directory of Tivoli Workload Scheduler.

–dbRoot <DB_home>The installation directory of the database.


13. Manually copy the master domain manager definition from the topology.deffile you exported in step 1 on page 242 (you can find it in export_dir) anduse composer new to add it in the DB2 database.

14. Run dataimport to import all scheduling object definitions and global optionsto DB2. Find this file in the bin subdirectory of the Tivoli Workload Schedulerhome directory.Run dataimport from a Windows or UNIX command prompt as follows:dataimport source_dir export_dir

where:

source_dirThe Tivoli Workload Scheduler installation directory.


For example:dataimport.cmd F:\TWS85\tws85user F:\TWS85\tws85user\export

The object definitions and the global options are retrieved from theF:\TWS85\tws85user\export directory and stored in the new DB2 database.


15. Run the following command to set the carry forward option to ALL:optman chg cf=ALL

16. Update the Symphony file by creating a plan with 0 extension period thatbegins at the end of the current plan:JnextPlan -from start_time -for 0000

where start_time is the date and time when the current plan ends.

You have now completed the reconfiguration steps.

To migrate a backup master domain manager, perform the following steps :v Stop the WebSphere Application Server using the conman stopappserver


v Perform steps 6 on page 245 to 11 on page 246.v Start the WebSphere Application Server using the conman startappserver


v Set the isBackupManager parameter of the createdb_root command (script) toTRUE.

Upgrading your database

If you want to upgrade your database, change the instance owner, or relocate it toa different host, the procedure for upgrading your database, changing the instanceowner, or relocating it, is as follows:1. If you are changing DB2, check the node directory and database directory and

make a note of the current configuration. To do this, issue the followingcommands at the DB2 command-line:db2 list node directory show detail

db2 list database directory

where the show detail attribute is specified to give the full information in thedirectory.Make a note of the displayed details.

2. Stop the application server, using the commandstopWas -direct -user <user> -password <password>

3. Make the upgrade, instance owner change, or relocation, of the databasefollowing the instructions from your database supplier.

4. If you have changed the database host, port, or database name, you will needto update the application server's data source properties, as described in“Changing the database host name, port, or database name” on page 285.

5. If you have changed the database access credentials, you will need to updatethe application server's security properties, as described in “Changing thesecurity settings” on page 296.

6. Reconfigure the database for Tivoli Workload Scheduler, as follows:

DB2

a. Check the node directory and database directory, as you did in step 1


b. If necessary, modify the data displayed by these commands tomatch the data you noted in step 1 on page 247. If you are notcertain of how to do this, contact IBM Software Support forassistance.

Oracle Check the Oracle Listener and make sure that the service name iscorrectly specified.

7. Restart the database.8. Restart the application server, using the command:

startWas -direct -user <user> -password <password>

Auditing facilitiesDescribes the audit facilities to track changes in the database and the plan, as wellas those that track changes to objects involved in dynamic workload scheduling.

Audit trails are useful to check enforcement and effectiveness of IT controls, foraccountability, and vulnerability and risk analysis. IT organizations can also useauditing of security-related critical activities to aid in investigations of securityincidents. When a security incident occurs, audit trails enable analysis of thehistory of activities (who did what, when, where, and how) that occurred prior tothe security incident, so appropriate corrective actions can be taken. For thesereasons, audit trails might need to be archived and accessible for years.

The auditing logs are created in XML format and can be viewed with a standardtext editor or parsed using third-party utilities.

You can also view the auditing logs using the Log and Trace Analyzer (LTA), acomponent of the IBM Autonomic Computing Toolkit. In general, the Log andTrace Analyzer is used for importing and correlating different logs generated bydifferent products. The Log and Trace Analyzer can be very useful in correlatingauditing logs with other logs from different sources, such as databases (DB2,Oracle), WebSphere Application Server, and the operating system. See the EngineLog Analyzer section on the Tivoli Workload Scheduler Troubleshooting for details.

Two separate audit trail facilities are provided:v Database and plan change tracking - see “Database and plan audit”v Tracking of changes to scheduling objects to support dynamic workload

scheduling - see “Dynamic workload scheduling audit” on page 254

Database and plan auditAn auditing option is available to track changes to the database and the plan. It isdisabled by default. It is described in these sections:v “How audit works”v “Enabling the audit feature” on page 249v “Audit log header format” on page 249v “Audit log body format” on page 250v “Sample audit log entries” on page 253

How audit worksThe storage of audit records varies depending on whether you maintain trails forthe database or the plan. You have the following options:


|

||

|||||||

||

|||||||

|

|

||

|

||

|

|

|

|

|

|||

http://publib.boulder.ibm.com/infocenter/tivihelp/v47r1/index.jsp?topic=/com.ibm.tivoli.itws.doc_8.6/awstrtroubleshooting.htm

database auditingYou can track changes to the database in a file, in the database itself, or inboth. All user modifications are logged, including the current definition ofeach modified database object. If an object is opened and saved, the actionis logged even if no modification has been done.

plan auditingYou can track changes to the plan in a file. All user modifications to theplan are logged. Actions are logged whether they are successful or not.

Each audit log provides audit information for one day, from 00:00:00 UTC to23:59:59 UTC regardless of the timezone of the local workstation, but the log file isonly created when an action is performed or the WebSphere Application Server isstarted.

The files are called yyyymmdd, and are created in the following directories:<TWA_home>/TWS/audit/plan

<TWA_home>/TWS/audit/database

Audit entries are logged to a flat text file on individual workstations in theTivoliWorkload Scheduler network. This minimizes the risk of audit failure due tonetwork issues. The log formats are the same for both plan and database in ageneral sense. The logs consist of a header portion which is the same for allrecords, an action ID, and a section of data which varies according to the actiontype. All data is kept in clear text and formatted to be readable and editable from atext editor such as vi or notepad.

Note: For modify commands, two entries are made in the log for resources,calendars, parameters and prompts. The modify command is displayed inthe log as a combination of the delete and add commands.

Enabling the audit featureThe auditing option is enabled by setting the following two entries in the globaloptions, using optman:

enPlanAudit = 0|1enDbAudit = 0|1

A value of 1 (one) enables auditing and a value of 0 (zero) disables auditing.Auditing is disabled by default on installation of the product.

To initiate database auditing, you must shut downTivoli Workload Schedulercompletely. When you restart Tivoli Workload Scheduler, the database audit log isinitiated. Plan auditing takes effect whenJnextPlan is run.

Audit log header formatEach log file starts with a header record that contains information about when thelog was created and whether it is a plan or database log.

The header record fields are separated by vertical bars ( | ), as follows:

HEADER|<GMT_date>|<GMT_time>|<local_date>|<local_time>|<object_type>| ><workstation>|<user_ID>|<version>| <level>


|||||

|||

||||

|

|

|

|||||||

|||

|||

||||

||

|||

|||

|

||||

Log TypeHEADER

GMT DateThe GMT date when the log file was created.

GMT TimeThe GMT time when the log file was created.

Local DateThe local date when the log file was created. The local date is defined bythe time zone option of the workstation.

Local TimeThe local time when the log file was created. The local time is defined bythe time zone option of the workstation.

Object TypeDATABASE for a database log file and PLAN for a plan log file.

Workstation NameThe Tivoli Workload Scheduler workstation name for which this file wascreated. Each workstation in the Tivoli Workload Scheduler networkcreates its own log.

User IDThe Tivoli Workload Scheduler user ID that created the log file.

VersionThe version of the file.

Level The logging level.

Audit log body formatThe audit log formats are basically the same for the plan and the database. The logconsists of a header portion, an action ID, and data sections that vary with theaction type. The data is in clear text format and each data item is separated by avertical bar ( | ).

The log file entries are in the following format:

<log_type>|<GMT_date>|<GMT_time>|<local_date>|<local_time>|<object_type>| ><action_type>|<workstation>|<user_ID>|<object_name>|<action_data_fields>

The log files contain the following information:

log_typeDisplays an eight character value indicating the source of the log record.The following log types are supported:

CONMANconman command text

DATABASEDatabase action

HEADERThe log file header

MAKESECmakesec run


||

||

||

|||

|||

||

||||

||

||

||

|||||

|

||||

|

|||

||

||

||

||

PARMSParameter command text

PLAN Plan action

RELEASErelease command text

STAGEMANstageman run

GMT_dateDisplays the GMT date the action was performed. The format is yyyymmddwhere yyyy is the year, mm is the month, and dd is the day.

GMT_timeDisplays the GMT time the action was performed. The format is hhmmsswhere hh is the hour, mm is the minutes, and ss is the seconds.

local_dateDisplays the local date the action was performed. The local date is definedby the time zone option of the workstation. The format is yyyymmdd whereyyyy is the year, mm is the month, and dd is the day.

local_timeDisplays the local time the action was performed. The local time is definedby the time zone option of the workstation. The format is hhmmss where hhis the hour, mm is the minutes, and ss is the seconds.

object_typeDisplays the type of the object that was affected by an action, from thefollowing:

DATABASEDatabase definition (for header only)

DBCALDatabase calendar definition

DBDOMAINDatabase domain definition

DBJBSTRMDatabase job stream definition

DBJOBDatabase job definition

DBPARMDatabase parameter definition

DBPROMPTDatabase prompt definition

DBRESDatabase resource definition

DBSECDatabase security

DBUSERDatabase user definition

DBVARTABDatabase variable table definition


||

||

||

||

|||

|||

||||

||||

|||

||

||

||

||

||

||

||

||

||

||

||

DBWKCLSDatabase workstation class definition

DBWKSTNDatabase workstation definition

PLAN Plan (for header only)

PLDOMAINPlan domain

PLFILEPlan file

PLJBSTRMPlan job stream

PLJOBPlan job

PLPROMPTPlan prompt

PLRESPlan resource

PLWKSTNPlan workstation

action_typeDisplays what action was performed on the object. The appropriate valuesfor this field are dependent on which action is being performed.

For the plan, the <action_type> can be ADD, DELETE, MODIFY, orINSTALL.

For the database, the ADD, DELETE and MODIFY actions are recorded forworkstation, workstation classes, domains, users, jobs, job streams,calendars, prompts, resources and parameters in the database.

The <action_type> field also records the installation of a new Security file.When makesec is run, Tivoli Workload Scheduler records it as an INSTALLaction for a Security definition object.

LIST and DISPLAY actions for objects are not logged.

For parameters, the command line with its arguments is logged.

workstationDisplays the Tivoli Workload Scheduler workstation from which the user isperforming the action.

user_IDDisplays the logon user who performed the particular action. On Windowsoperating systems, if the user who installed WebSphere Application Serverwas a domain user, for Log Types stageman and conman this fieldcontains the fully qualified user ID domain\user.

object_nameDisplays the fully qualified name of the object. The format of this fielddepends on the object type as shown here:

DATABASEN/A


||

||

||

||

||

||

||

||

||

||

|||

||

|||

|||

|

|

|||

|||||

|||

||

DBCAL<calendar>

DBDOMAIN<domain>

DBJBSTRM<workstation>#<job_stream>

DBJOB<workstation>#<job>

DBPARM<workstation>#<parameter>

DBPROMPT<prompt>

DBRES<workstation>#<resource>

DBSECN/A

DBUSER[<workstation>#]<user>

DBVARTAB<variable_table>

DBWKCLS<workstation_class>

DBWKSTN<workstation>

PLAN N/A

PLDOMAIN<domain>

PLFILE<workstation>#<path>(<qualifier>)

PLJBSTRM<workstation>#<job_stream_instance>

PLJOB<workstation>#<job_stream_instance>.<job>

PLPROMPT[<workstation>#]<prompt>

PLRES<workstation>#<resource>

PLWKSTN<workstation>

action_data_fieldsDisplays the action-specific data fields. The format of this data isdependent on the <action_type> field.

Sample audit log entries:

This is a sample database audit log:


||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

|||

|

|

HEADER |20080207|084124|20080207|094124|DATABASE| |WK1| | | |Version=A1.0| Level=1

DATABASE|20080207|084124|20080207|094124|DBRES |ADD |WK1|operator1| |res=WK1#RESOURCE |

DATABASE|20080207|100524|20080207|110524|DBWKSTN |MODIFY|WK1|operator1| |ws=TIVOLI10 |

DATABASE|20080207|100525|20080207|110525|DBWKSTN |MODIFY|WK1|operator1| |ws=ASLUTRI1 |

DATABASE|20080207|100525|20080207|110525|DBWKSTN |MODIFY|WK1|operator1| |ws=WK1 |

DATABASE|20080207|100526|20080207|110526|DBDOMAIN|MODIFY|WK1|operator1| |dom=MASTERDM |

DATABASE|20080207|100610|20080207|110610|DBWKSTN |MODIFY|WK1|operator1| |ws=TIVOLI10 |

DATABASE|20080207|100610|20080207|110610|DBWKSTN |MODIFY|WK1|operator1| |ws=ASLUTRI1 |

DATABASE|20080207|100611|20080207|110611|DBWKSTN |MODIFY|WK1|operator1| |ws=WK1 |

DATABASE|20080207|100611|20080207|110611|DBWKSTN |ADD |WK1|operator1| |ws=WK2 |

DATABASE|20080207|100612|20080207|110612|DBDOMAIN|MODIFY|WK1|operator1| |dom=MASTERDM |

This is a sample plan audit log:

HEADER |20080207|100758|20080207|110758|PLAN | |WK1|admin| | |Version=A1.0|Level=1

STAGEMAN|20080207|100758|20080207|110758|PLAN |INSTALL|WK1|admin| |C:\IBM\TWS\oper1\Symphony|AWSBHV030I The new Symphony file is installed.

STAGEMAN|20080207|100758|20080207|110758|PLAN |INSTALL|WK1|admin| |C:\IBM\TWS\oper1\Sinfonia|AWSBHV036I Multi-workstation Symphony file copied to C:\IBM\TWS\oper1\Sinfonia

STAGEMAN|20080207|100758|20080207|110758|ADITLEVL|MODIFY |WK1|admin| | |AWSBHV077I Audit level changing from 0 to 1.

CONMAN |20080207|100800|20080207|110800|PLWKSTN |MODIFY | |admin| |WK1 |continue & start

CONMAN |20080207|100941|20080207|110941|PLWKSTN |MODIFY | |admin| |SLUTRI1 |limit cpu=slutri1;10

PLAN |20080207|101018|20080207|111018|PLWKSTN |MODIFY |WK1|oper1| |WK1 |limit cpu=SLUTRI1;20

PLAN |20080207|101028|20080207|111028|PLDOMAIN|MODIFY |WK1|oper1| |ECCOLO |reply ECCOLO;yes

A ResetPlan command run against the current production plan is stored in theplan audit log file as follows:

STAGEMAN|20080207|100758|20080207|110758|PLAN|DELETE|WK1|admin||/home/WK1/schedlog/M200803140127|

AWSBHV025I The old Symphony file renamed /home/WK1/schedlog/M200803140127

Dynamic workload scheduling auditDescription

When you select the dynamic scheduling capability at installation time, theauditing feature is automatically installed. By default, the auditing feature isdisabled.


|

|||||||||||||||||||||

|

|

||||||||||||||||||||||

||

|||

|

|

|||

Auditable events are as follows:

JobDefinitionAuditEventMaintains a track of operations performed on job definitions.

JobLogAuditEventMaintains a track of operations performed on job logs.

JobAuditEventMaintains a track of operations performed on jobs.

ResourceAuditEventMaintains a track of operations performed on resources.

RelationshipAuditEventMaintains a track of operations performed on relationships betweenresources.

RecoveryActionAuditEventMaintains a track of operations performed on recovery actions.

HistoryDataAuditEventMaintains a track of operations performed on historical data.

To configure the auditing of events, enable the auditing feature and optionallychange the default values in the configuration file to define event types to beaudited. The configuration file is located in the following path:TWA_home\TDWB\config\audit.properties

Configuring the audit

Configure one or more of the properties in the audit.properties file to enable andconfigure auditing:

audit.enabledSpecifies whether the auditing feature is enabled or disabled. The defaultvalue is false. Supported values are as follows:

false The auditing feature is not enabled.

true The auditing feature is enabled.

onSecurityEnabledThe auditing feature is enabled if global security is enabled on theWebSphere Application Server.

audit.consumer.file.auditFilePrefixSpecifies the file prefix for the auditing log file. The file name is definedusing the file prefix plus the _auditN.log suffix, where N is a progressivenumber. If you want the date and time of the file creation specified in thefile prefix, use the default format: ‘tdwb_'yyyy-MM-dd. For instance, usingthe default prefix ‘tdwb_'yyyy-MM-dd generates the tdwb_2010-12-20_auditN.log family of files. Note that the text between single quotes (') isnot processed by the program and remains unchanged. This format createsa different file for each day the auditing feature is enabled. Also, changingthe prefix to ‘tdwb_'yyyy-MM generates the tdwb_2010-12_auditN.logfamily of files. This format creates a different file for each month theauditing feature is enabled.

You can modify this format as desired to create files on a weekly, monthlyor yearly basis, depending on your auditing requirements. Depending onthe date and time format you choose, the maximum size and number of


|

||

||

||

||

|||

||

||

|||

|

|

||

|||

||

||

|||

||||||||||||

|||

log files vary. The maximum size and number of log files are defined usingthe audit.consumer.file.maxFileSize andaudit.consumer.file.maxAuditFiles properties respectively. Use these threeparameters to control the size of the audit logs stored. For example, usingthe default values for these parameters, then every day you will have amaximum of 10 MB x 100 files each day. Once the maximum is reached,the first file created is overwritten. If you want use less space to store auditlogs, you can decided to change the maximum number of files or onlyhave files on a monthly basis, by specifying the format for theaudit.consumer.file.auditFilePrefix property as ‘tdwb_'yyyy-MM.

audit.consumer.file.auditFileLocationSpecifies the path where the log files are created. The default path is/audit.

audit.consumer.file.maxFileSizeSpecifies the maximum size in bytes of the log files. When a file reachesthe maximum size, a new log file is created. The default value is 10000000bytes (10 MB). This is also the highest supported value.

audit.consumer.file.maxAuditFilesSpecifies the maximum number of files with a specific prefix. When allfiles reach the maximum size and the maximum number of files isexceeded, the oldest file with a specific prefix is overwritten. The defaultvalue is 100 files. This is also the highest supported value.

Configuring dynamic audit events

The following table lists the supported actions and properties for each event withthe related default values. You can configure these values in the audit.propertiesfile.

Table 51. Auditable event properties

Event Action Property Default value

JobDefinitionAuditEvent create audit.tdwb.JobDefinitionAuditEvent.create.enabled true

delete audit.tdwb.JobDefinitionAuditEvent.delete.enabled true

get audit.tdwb.JobDefinitionAuditEvent.get.enabled true

query audit.tdwb.JobDefinitionAuditEvent.query.enabled false

update audit.tdwb.JobDefinitionAuditEvent.update.enabled true

JobLogAuditEvent get audit.tdwb.JobLogAuditEvent.get.enabled true

JobAuditEvent cancel audit.tdwb.JobAuditEvent.cancel.enabled true

get audit.tdwb.JobAuditEvent.get.enabled true

query audit.tdwb.JobAuditEvent.query.enabled false

submit audit.tdwb.JobAuditEvent.submit.enabled true

ResourceAuditEvent create audit.tdwb.ResourceAuditEvent.create.enabled true

delete audit.tdwb.ResourceAuditEvent.delete.enabled true

query audit.tdwb.ResourceAuditEvent.query.enabled false

resume audit.tdwb.ResourceAuditEvent.resume.enabled true

suspend audit.tdwb.ResourceAuditEvent.suspend.enabled true

update audit.tdwb.ResourceAuditEvent.update.enabled true


||||||||||

|||

||||

|||||

|

|||

||

||||

||||

|||

|||

|||

|||

||||

||||

|||

|||

|||

||||

|||

|||

|||

|||

|||

Table 51. Auditable event properties (continued)

Event Action Property Default value

RelationshipAuditEvent create audit.tdwb.RelationshipAuditEvent.create.enabled true

delete audit.tdwb.RelationshipAuditEvent.delete.enabled true

query audit.tdwb.RelationshipAuditEvent.query.enabled false

RecoveryActionAuditEvent invoke audit.tdwb.RecoveryActionAuditEvent.invoke.enabled true

HistoryDataAuditEvent move audit.tdwb.HistoryDataAuditEvent.move.enabled true

By default, auditing is disabled for query actions, while all the other actions areenabled. If the auditing feature is disabled, all properties are ignored.

Log file specificationsThe elements used in the auditing log files are extensions to the Common BaseEvent (CBE) schema. The types and elements listed below are available in theauditing log files. Supported action types for each element are listed in Table 51 onpage 256.

ActionRepresents the action that is being taken. Each auditable event supports adifferent set of possible actions. See Table 51 on page 256. The Action typecontains the following element:

Table 52. Elements in Action type

Element name Element descriptionAlways returned in theoutput

Action The action type that is beingtaken on thedynamicworkload broker object.

Yes

ObjectInfoListRepresents a list of dynamic workload broker objects. The ObjectInfoListtype contains the following element:

Table 53. Elements in ObjectInfoList type


objectInfo The class of the object beinginvolved in the action

Yes

ObjectInfoRepresents information about a dynamic workload broker object in anobjectInfoList type or in another objectInfo element. The ObjectInfotype contains the following elements:

Table 54. Elements in ObjectInfo type


objectClass The class of the object beinginvolved in the action.

Yes

objectName The name of the dynamicworkload broker object.

Only if available


|

||||

||||

|||

|||

||||

|||||

||

|||||

||||

||

||||

||||

|

|

|||

||

||||

||||

|

||||

||

||||

||||

||||

Table 54. Elements in ObjectInfo type (continued)


objectNamespace The namespace of thedynamic workload brokerobject.

Only if available

objectType The type of the dynamicworkload broker object.

Only if available

objectAlias The alias of the dynamicworkload broker object.

Only if available

objectIdentifier The unique identifier of thedynamic workload brokerobject.

Only if available

objectRole The role of the dynamicworkload broker object, ifany. For instance a Resourcecan have the source ordestination role in arelationship

Only if available

objectSubmitterType The type of the componentwhich submitted theoperation. The component isone of the following:

v Tivoli Dynamic WorkloadBroker Console

v Command line

v Dynamic workload brokerworkstation

v Third party utility

Only if available

objectInfo A child objectInfo object.For instance, a relationship isalways related to tworesources.

Only if available

OutcomeDefines the outcome of a security event. The Outcome type contains thefollowing elements:

Table 55. Elements in Outcome type


result The status of the event. Thisinformation can be usedwhen filtering theinformation in the log file.

Yes

failureReason Additional information onthe outcome of the operation.

Yes, if the operation wasunsuccessful.

UserInfoListRepresents a list of userInfo elements, each representing the list of users inthe delegation chain. The UserInfoList type contains the followingelement:


|

||||

||||

|

||||

||||

||||

|

|||||||

|

|||||

||

|

||

|

|

|||||

|

|

|||

||

||||

|||||

|

||||||

||||

Table 56. Elements in UserInfoList type


objectInfo An array of Informationabout each user in thedelegation chain. The firstuserInfo element identifiesthe user which authenticatedfirst. The last userInfoelement identifies the userwith whose credentials theaction is being taken.

Yes

UserInfoRepresents information about a user. Elements of this type returninformation about the user involved in the operation being audited. TheUserInfo type contains the following element:

Table 57. Elements in UserInfo type


UserInfo The username provided todynamic workload broker forauthentication.

Yes

How to perform queries on log filesLog files can be very long and detailed. When you view your log files with theLog and Trace Analyzer, you can apply one or more queries to filter information inthe file and make searches faster. You can use the following queries to filter onlythe relevant information or you can create your own queries depending on yourrequirements. The following queries are written in XPath query language.v To filter all the events generated by a specific user:

/CommonBaseEvent [extendedDataElements/children[@name='userInfo' andvalues='username']]

v To filter all the events related to a specific object class:/CommonBaseEvent [ extendedDataElements//children[@name='objectClass'and values='Resource]]

v To filter all the events related to a specific object://CommonBaseEvent [ extendedDataElements//children[@name='objectName'and values='myresource']/../children[@name='objectClass' andvalues='Resource']]

v To filter all the events related to a specific action:/CommonBaseEvent [extendedDataElements[@name='action' andvalues='uninstall']]

v To filter all the events with SUCCESSFUL outcome:/CommonBaseEvent [extendedDataElements/children[@name='result' andvalues='SUCCESSFUL']]

The following query returns all create actions:/CommonBaseEvent[ extendedDataElements[@name = ’action’ and values = ’create’]]

You can export this query into an XML file as follows:


||

||||

||||||||||

|

|

||||

||

||||

||||

|

|

||||||

|

||

|

||

|

|||

|

||

|

||

|

|

|

<?xml version="1.0" encoding="UTF-8"?><cbeviewer_configuration><logParserSets>

<logParserSet description="Parser for CBE log"id="com.ibm.cbeviewer.parsers.cbeLogParserSet"label="Common Base Event log"parentId="com.ibm.cbeviewer.parsers.jdLogParserSet"/>

<logParserSet description="Parser for CEI Server"id="com.ibm.cbeviewer.parsers.ceiLogParserSet"label="Common Event Infrastructure server"parentId="com.ibm.cbeviewer.parsers.jdLogParserSet"/>

<logParserSet description="Other parsers"id="com.ibm.cbeviewer.parsers.otherParsersLogParserSet"label="Other parsers"/>

</logParserSets><recent_expressions>

<xpath name="All Create Events">/CommonBaseEvent[ extendedDataElements[@name = ’action’ and values = ’create’]]</xpath>

</recent_expressions></cbeviewer_configuration>

The following is a short example of a log file:<CommonBaseEvent

creationTime="2007-06-06T14:26:23.311Z"extensionName="TDWB_JOB_AUDIT_EVENT"globalInstanceId="CEFC6DD156CA54D902A1DC1439E6EC4ED0"sequenceNumber="1"version="1.0.1">

<extendedDataElementsname="userInfoList"type="noValue">

<childrenname="userInfo"type="string">

<values>UNAUTHENTICATED</values></children>

</extendedDataElements><extendedDataElements

name="action"type="string">

<values>submit</values></extendedDataElements><extendedDataElements

name="outcome"type="noValue">

<childrenname="result"type="string">

<values>SUCCESSFUL</values></children>

</extendedDataElements></CommonBaseEvent>

Examples

The following examples describe a standard usage of the auditing feature.

In the following example, user root successfully retrieves the definition of a jobnamed MyTestJob using the jobstore command.<CommonBaseEvent

creationTime="2007-06-21T16:05:19.455Z"extensionName="TDWB_JOB_AUDIT_EVENT"globalInstanceId="CE8F5E102AE3419AF7A1DC201135463A40"sequenceNumber="188"version="1.0.1">

<extendedDataElements


|||||||||||||||||||

|

||||||||||||||||||||||||||||||

|

|

||

|||||||

name="userInfoList"type="noValue">


<values>root</values></children>



<values>get</values></extendedDataElements><extendedDataElements



<values>SUCCESSFUL</values></children>


name="objectInfoList"type="noValue">

<childrenname="objectInfo"type="noValue">

<childrenname="objectClass"type="string">

<values>Job</values></children><children

name="objectName"type="string">

<values>MyTestJob</values></children><children

name="objectIdentifier"type="string">

<values>3ebf6d62-0b83-3270-9b83-83c393e9cbca</values></children><children

name="objectSubmitterType"type="string">

<values>TDWB CLI</values></children>

</children></extendedDataElements><extendedDataElements

name="CommonBaseEventLogRecord:sequenceNumber"type="long">

<values>80808</values></extendedDataElements><extendedDataElements

name="CommonBaseEventLogRecord:threadID"type="int">

<values>280</values></extendedDataElements><sourceComponentId

application="JobManagement"component="None"componentIdType="Application"location="tdws08"locationType="Hostname"subComponent="None"threadId="Default : 84"componentType="http://www.ibm.com/namespace/autonomic/Tivoli_componentTypes"/>

<situationcategoryName="ReportSituation">


|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

<situationTypexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="ReportSituation"reasoningScope="INTERNAL"reportCategory="SECURITY"/>

</situation></CommonBaseEvent>

In the following example, user testuser tries deleting a job instance namedMySecondJob using the appropriate command line. The operation fails becausethe job was submitted by another user. Deleting jobs submitted by other usersrequires Operator or Administrator rights. For more information on access rights,see IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically or IBM TivoliWorkload Scheduler: Administration Guide.<CommonBaseEvent

creationTime="2007-06-21T16:05:32.746Z"extensionName="TDWB_JOB_AUDIT_EVENT"globalInstanceId="CE8F5E102AE3419AF7A1DC20113D32BB20"sequenceNumber="189"version="1.0.1">

<extendedDataElementsname="userInfoList"type="noValue">


<values>testuser</values></children>



<values>cancel</values></extendedDataElements><extendedDataElements



<values>UNSUCCESSFUL</values></children><children

name="failureReason"type="string">

<values>userNotAuthorized</values></children>


name="objectInfoList"type="noValue">

<childrenname="objectInfo"type="noValue">

<childrenname="objectClass"type="string">

<values>Job</values></children><children

name="objectName"type="string">

<values>MySecondJob</values></children><children

name="objectIdentifier"type="string">

<values>a05732c8-c008-3103-afd1-84b567d78de7</values></children>


|||||||

||||||

|||||||||||||||||||||||||||||||||||||||||||||||||||||||

<childrenname="objectSubmitterType"type="string">

<values>TDWB CLI</values></children>

</children></extendedDataElements><extendedDataElements

name="CommonBaseEventLogRecord:sequenceNumber"type="long">

<values>80964</values></extendedDataElements><extendedDataElements

name="CommonBaseEventLogRecord:threadID"type="int">

<values>292</values></extendedDataElements><sourceComponentId

application="JobManagement"component="None"componentIdType="Application"location="tdws08"locationType="Hostname"subComponent="None"threadId="Default : 91"componentType="http://www.ibm.com/namespace/autonomic/Tivoli_componentTypes"/>

<situationcategoryName="ReportSituation">

<situationTypexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="ReportSituation"reasoningScope="INTERNAL"reportCategory="SECURITY"/>

</situation></CommonBaseEvent>

Keeping track of database changes using audit reportsTo keep always track of the changes that impact objects stored in the database, youcan use the following audit reports, which can be run in batch mode using thecommand line interface:

General audit reportThe report provides information about objects that have been modified inthe database. More specifically, it details who made the change, on whichobjects, and when.

Details reportThe report provides further details about the changes implemented. Itspecifies who made the change, on which objects, when, and what hasbeen changed. More specifically it shows the object definition before andafter the change.

A sample business scenario

The administrator of an insurance company needs to keep track of all the changesimpacting the insurance policies, conditions and terms of all the customersregistered in the company database. To do it, the administrator periodically runsthe audit general and details reports.

To satisfy this request, he creates an audit general report that provides detailsabout which TWS objects have been modified in the database, who modified themand on which date. Then, to find out more details about the changes, he alsocreates an audit details report.


|||||||||||||||||||||||||||||||||||

|

|||

||||

|||||

|

||||

||||

To accomplish his task, he runs the following steps:1. He customizes the property files related to the audit reports, specifying the

format and content of the report output.2. He schedules jobs to obtain the reports:

a. The first job generates an audit to be saved locally.b. The second job runs a detail report overnight to retrieve more details about

the specific changes implemented. The report output is sent using an mailto the analyst. The information collected is used to keep all the insurancebranch offices updated with any change and news.

3. The administrator adds the two jobs to a job stream scheduled to run weeklyand generates the plan.

Setting up for command line reporting

Before running these reports you must perform a few setup steps:1. The software needed to run these reports is contained in a package named

TWSBatchReportCli included in the Tivoli Workload Scheduler installationimage, in the TWSBatchReportCli directory. If you plan to run them from withina scheduled job, extract the package file on one of the platforms listed inhttp://www.ibm.com/support/docview.wss?rs=672&uid=swg27020800After extracting the package, you obtain the following file structure:

Because the native UNIX tar utility does not support long file names, if you areextracting the files on AIX®, Solaris, or HP-UX systems, ensure that the latestGNU version of tar (gtar) is installed to extract the files successfully.

Note:

a. Make sure you run the following commands in the directory whereyou extracted the files:

On UNIXchmod -R +x *chown -R username *

On WindowsEnsure Tivoli Workload Scheduler is installed.setown -u username *

Where username is the Tivoli Workload Scheduler user that will runthe reports.

b. If you plan to schedule jobs that run these reports, the system whereyou extract the package must be accessible as network file systemfrom a fault-tolerant agent defined in the local schedulingenvironment.


|

||

|

|

||||

||

|

|

|||||

||

|

|||

|

||

|

||

||

|

||

||||


2. Configure the template file .\config\common.properties specifying theinformation to:a. Connect to the database where the historical data are stored.b. Set the date and time format, including the time zone. The file

.\config\timezone.txt contains a list of time zones supported by TivoliWorkload Scheduler and the information on how to set them. The time zonenames are case sensitive.

c. Make available the report output on the URL specified in ContextRootUrlfield. This is an example of configuration settings:####################################################################### HTTP Server information######################################################################

#Specify the context root where the report will be available#To leverage this possibility it needs to specify in the report output dir#the directory that is referred by your HTTP Server with this contect root

ContextRootUrl=http://myserver/reportoutput

In this case make sure that the output_report_dir specified when running thereports command points to the same directory specified in theContextRootUrl.

d. Send the report output using a mail. This is an example of configurationsettings:####################################################################### Email Server configuration######################################################################PARAM_SendReportByEmail=true

#SMTP servermail.smtp.host=myhost.mydomain.com#IMAP providermail.imap.socketFactory.fallback=falsemail.imap.port=993mail.imap.socketFactory.port=993#POP3 providermail.pop3.socketFactory.fallback=falsemail.pop3.port=995mail.pop3.socketFactory.port=995

####################################################################### Email properties######################################################################PARAM_EmailFrom=user1@your_company.comPARAM_EmailTo=user2@your_company.com,user3@your_company.comPARAM_EmailCC=user4@your_company.comPARAM_EmailBCC=user5@your_company.comPARAM_EmailSubject=Test send report by emailPARAM_EmailBody=This is the report attached

An explanation of all the customizable fields is contained in the template file.

Running audit reports from the command lineTo run audit report on the database, you must first enable the audit feature andconfigure the audit options described in “Global options - detailed description” onpage 13.

The \reports\templates directory contains a sample template file for each type ofreport.


||

|

||||

||

|||||||||

|||

||

|||||||||||||||||||||||||

|

||||

||

Before running any of these reports make sure you customize the correspondingtemplate file, either ad.properties or ag.properties.

In that file, named report_name.properties, you can specify:v The information to display in the report header.v How to filter the information to display the expected result.v The format and content of the report output.

For more information about the specific settings see the explanation provided inthe template file beside each field.

After you set up the environment as it is described in “Setting up for commandline reporting” on page 264, and you configured report template file, use thefollowing syntax to run the report:

reportcli -p report_name.property[-o output_report_dir][-r report_output_name][-k key=value ][-k key=value ].......

where:

-p report_name.propertySpecifies the path name to the report template file.

-o routput_report_dirSpecifies the output directory for the report output.

-r report_output_nameSpecifies the name of the report output.

-k key=valueSpecifies the value of a settings. This value override the correspondingvalue, if defined, in the common.properties file or in thereport_name.properties file.

Examples:

1. In this example the reportcli.cmd is run with the default parameter:reportcli.cmd -p D:\ReportCLI\TWSReportCli\reports\templates\ag.properties-r audit1

2. In this example the reportcli.cmd is run using the -k parameter to override thevalues set for PARAM_DateFormat in the .\config\common.properties file:reportcli.cmd -p D:\ReportCLI\TWSReportCli\reports\templates\ag.properties-r audit2 -k PARAM_DateFormat=short

3. In this example the reportcli.cmd is run using the -k parameter to override heformat specified for the report output in the .properties file:./reportcli.sh -p /TWSReportCli/REPCLI/reports/templates/ag.properties-r audit3 -k REPORT_OUTPUT_FORMAT=html -k OutputView=charts

Note: If the report is run through a Tivoli Workload Scheduler job, the output ofthe command is displayed in the job output.


||

|

|

|

|

||

|||

||||||

|

||

||

||

||||

|

|

||

||

||

||

||

|||

Chapter 9. Administrative tasks

This chapter describes how to perform some specific administrative tasks on TivoliWorkload Scheduler, as follows:

The tasks

“Changing a domain manager or dynamic domain manager” on page 269Change a domain manager or dynamic domain manager, either inthe event of the failure of the computer where it is installed, or aspart of a planned replacement activity.

“Changing a master domain manager” on page 270Change a master domain manager, either in the event of the failureof the computer where it is installed, or as part of a plannedreplacement activity.

“Changing key Tivoli Workload Scheduler passwords” on page 274Change the password of the TWS_user, or any other of the usersthat have an infrastructure role in Tivoli Workload Scheduler.

“Unlinking and stopping Tivoli Workload Scheduler” on page 283The correct procedure to unlink the master domain manager fromits agents and stop the master processing.

“Changing the database host name, port, or database name” on page 285If you need to change the host, port or name of the database, effectthe change in the application server, where the data sourceconfiguration is maintained.

“Changing the workstation host name or IP address” on page 291Change the host name or IP address of a workstation.

“Changing the security settings” on page 296If you need to update the properties that define your SSLconnection or authentication mechanism, you need to make thechanges in the embedded WebSphere Application Server

“Managing the event processor” on page 297If you are using event-driven workload automation, you will needto perform periodic maintenance on the event processor.

“Starting, stopping, and displaying dynamic workload broker status” onpage 298

The procedure to start or stop dynamic workload broker.

Application server tasksThe following tasks might need to be performed on the applicationserver:

“Application server - starting and stopping” on page 300How to stop and start the application server when youneed to.

“Application server - automatic restart after failure” on page 301The application server is managed by a utility that restartsit if it stops for any reason (subject to a configurablepolicy). This section describes how to modify the policyand deal with any situations that the policy cannot handle.


“Application server - encrypting the profile properties files” onpage 305

Several of the application server configuration files containpasswords. To avoid that these remain in the files in plaintext, run a utility to encrypt them.

“Application server - updating the Windows services aftermodifications” on page 305

On Windows, after changing certain data you must alsoupdate the Windows service that runs the embeddedWebSphere Application Server.

“Application server - updating the SOAP properties afterchanging the WebSphere Application Server user or itspassword” on page 306

On UNIX or Linux operating systems, if you have changedthe user ID or the password of the WebSphere ApplicationServer administration user either for Tivoli WorkloadScheduler or the Dynamic Workload Console, you mustalso update the SOAP client properties.

“Application server - configuration files backup and restore” onpage 307

The application server configuration manages the datasource and security aspects of your Tivoli WorkloadScheduler environment. The files should be regularlybacked up and when necessary can be restored.

“Application server - changing the host name or TCP/IP ports”on page 308

If you need to change the host or ports used by theapplication server, follow the correct procedure.

“Application server - changing the trace properties” on page 311The application server has a trace facility. This sectiondescribes how to increase the trace level to obtain moreinformation for troubleshooting, and how to reduce thelevel to improve performance.

Changing the application server properties

Several of the above tasks require you to run a common procedurewhereby you:1. Run a utility that displays a set of current application server properties

and saves them to a file2. Edit the file to change the properties3. Run another procedure to update the application server with the

changed properties

This procedure is fully described in “Application server - using the utilitiesthat change the properties” on page 312

Application server utilities reference informationSome reference information on the application server utilities is alsoprovided in “Application server utilities” on page 313. For further reading,see IBM Redbooks®: WebSphere Application Server V6 System Management &Configuration Handbook.


Changing a domain manager or dynamic domain manager

A domain manager or dynamic domain manager might need to be changedbecause you want it to run on a different workstation, or it might be forced on youas the result of network linking problems or the failure of the domain manager ordynamic domain manager workstation itself. This section, and its subsections,describes how to prepare for and use a backup domain manager or dynamicdomain manager. However, if the domain manager to be changed is a masterdomain manager, there are some specific additional steps to perform; see“Changing a master domain manager” on page 270.

Running without a domain manager has the following effects:v Agents and subordinate domain managers cannot resolve inter-workstation

dependencies, because activity records broadcast by the master domain managerare not being received.

v The upward flow of events is interrupted. This impacts events that report thestatus of jobs, job streams and dependencies defined on workstations in theTivoli Workload Scheduler network hierarchy under the failed domain manager.

v Standard agents that are hosted by the failed domain manager cannot performany processing, since they depend on the domain manager for all schedulingand job launching.

If the problem is expected to be of short duration, you can wait for the problem tobe resolved and Tivoli Workload Scheduler will recover on its own, as described inthe Tivoli Workload Scheduler: Troubleshooting Guide in the section about networklinking problems. If you are uncertain about the duration, or if you want to restorenormal agent operation, you must switch to a backup, as described in thefollowing sections.

Choosing a backup domain manager or backup dynamicdomain manager

Being prepared for network problems makes recovery easier. Set up a backupdomain manager or backup dynamic domain manager respectively for eachdomain manager or dynamic domain manager in your network to more easilyensure that Tivoli Workload Scheduler peak job scheduling loads are met. Chooseany fault-tolerant agent in the domain to be a backup domain manager or backupdynamic domain manager.

Setting up a backup domain managerEnsure that the FullStatus mode is selected in the backup domain manager orbackup dynamic domain manager workstation definition.

Also ensure that the backup domain manager is synchronized with respect to timewith the domain manager. The most secure way is to use a Network Time ProtocolServer to control the time on both systems, with the same repeat interval.

Network securityNetwork security is enforced using IP address validation. As a consequence,workstation linking (autolink option or link command) might fail if an agent hasan old Symphony file that does not contain the new domain manager. If aconnection fails, remove the old Symphony file on the agent and retry theconnection.

Chapter 9. Administrative tasks 269

|

||||||||

|

|||

|||

|||

||||||

|

|

||||||

|

||

|||

|

|||||

Switching a domain managerUse one of these procedures when you have a short-term loss of a domainmanager.

Using the command lineSee the procedure described under the switchmgr command in the TivoliWorkload Scheduler: User's Guide and Reference.

Using the Dynamic Workload Console

1. Launch the Dynamic Workload Console2. Connect to the engine of the current domain manager3. Select All workstations in Plan

4. Select the workstation you want to become the domain manager5. Click the More action6. Select Become Domain Manager.7. Click OK.

Domain managers remain switched until you perform another switch manageroperation, or run JnextPlan. To return to the original domain manager withoutrunning JnextPlan, repeat this procedure.

Switching a dynamic domain managerUse the procedure described in “Switching a master domain manager or dynamicdomain manager” on page 273 when you have a short-term loss of a dynamicdomain manager. The configuration information defined in the dynamic workloadbroker installed with the dynamic domain manager is automatically saved in theTivoli Workload Scheduler database. When you switch to the backup dynamicdomain manager, this information is automatically applied to the backup dynamicdomain manager.

Changing a master domain manager

If you lose or want to plan to change a master domain manager, all the commentsin the section “Changing a domain manager or dynamic domain manager” onpage 269 apply, but in addition consider the following:

Choosing a workstation for backup master domain managerSince you must transfer files between the master domain manager and its backup,the workstations must have compatible operating systems. Do not combine UNIXwith Windows workstations, and in UNIX, do not combine big-endianworkstations (HP-UX, Solaris, and AIX) with little-endian workstations (mostIntel-based operating systems, including Windows and Linux).

See the Tivoli Workload Scheduler: Planning and Installation Guide for details of theprerequisite requirements of a backup master domain manager.

Promoting an agent to backup master domain managerIt is the normal process to install a backup master domain manager when you setup your scheduling network. However, if you have not done so, and decide laterthat you need a backup master domain manager, you have two options:v Install a backup master domain manager on a system that is not currently in the

workload scheduling network. Follow the instructions in the Tivoli WorkloadScheduler: Planning and Installation Guide


|

||

|||

|

|

|

|

|

|

|

|

|||

|

|||||||

v Promote an agent to backup master domain manager. This option istime-consuming and requires you to interrupt your workload schedulingactivities, but if you want to do it, follow the procedure described in this section

You cannot promote an agent to backup master domain manager, using a commandor procedure that allows continuity of workload scheduling activities.

Instead, if you need to change an agent workstation to become the backup masterdomain manager, you must interrupt the workload scheduling activities. Theprocedure is as follows:1. Check that the workstation satisfies the prerequisites for a backup master

domain manager2. If it does, stop and disable all workload scheduling operations on the

workstation3. Uninstall the agent, following the instructions in the Tivoli Workload Scheduler:

Planning and Installation Guide

4. Install the backup master domain manager on the system where the agent wasinstalled, following the instructions in the Tivoli Workload Scheduler: Planning andInstallation Guide

5. Ensure that the database entry for the workstation is correct for a backupmaster domain manager (see the Tivoli Workload Scheduler: User's Guide andReference for information about the workstation definition

6. Define and start any workload scheduling operations you require on theworkstation in its new role.

Setting up a backup master domain managerEnsure that the master domain manager and the backup master domain managerhave FullStatus turned on in the workstation definition. This is important if youneed to resort to long-term recovery, where the backup master domain managergenerates a Symphony file (runs JnextPlan). If FullStatus is not turned on, the formermaster domain manager shows up as a regular fault-tolerant agent after the firstoccurrence of JnextPlan. During normal operations, the JnextPlan job automaticallyturns on the FullStatus flag for the master domain manager, if it is not alreadyturned on. When the new master domain manager runs JnextPlan, it does notrecognize the former master domain manager as a backup master domain managerunless the flag is enabled. The former master domain manager does not have anaccurate Symphony file when the time comes to switch back.

Also ensure that the backup master domain manager is synchronized with respectto time with the master domain manager. The securest way is to use a NetworkTime Protocol Server to control the time on both systems, with the same repeatinterval.

Copying files to use on the backup master domain managerTo back up the important master domain manager files to the backup masterdomain manager, use the following procedure:1. Copy the Security file on the master domain manager to the <TWA_home>/TWS

directory on the backup master domain manager. Add a suffix to the file sothat it does not overwrite the backup master domain manager's own Securityfile, for example, Security_from_MDM.

2. Copy all files in the <TWA_home>/TWS/mozart directory.


3. Copy the localopts file (see “Setting local options” on page 23 for thelocation). Add a suffix to the file so that it does not overwrite the backupmaster domain manager's own localopts file; for example,localopts_from_MDM.

This procedure must be performed each production period, or whenever there aresignificant changes to any objects. It can be incorporated into a script.

In addition to these required files, you might also want to copy the following:v Any scripts you might have written.v Archived Symphony files, for reference.v Log files, for reference.

Note: Another approach could be to place all of the above files on a separatelymountable file system, that could easily be unmounted from the masterdomain manager and mounted on the backup master domain manager inthe event of need. You would almost certainly want to backup these files inaddition, to protect against loss of the separately mountable file system.

To prevent the loss of messages caused by a master domain manager error, youcan use the fault-tolerant switch-manager facility.

Switching a master domain managerUse the procedure described in “Switching a domain manager” on page 270 whenyou have a short-term loss of a master domain manager.

Master domain managers remain switched until you perform another switchmanager operation. To return to the original master domain manager, repeat thisprocedure before the next production period turnover, unless you do not expectthe master domain manager to be available for the next production periodturnover (final job stream and JnextPlan job). In this case, use the procedure in thefollowing section.

Extended loss or permanent change of master domainmanager

Use the following procedure to switch to the backup if the original master domainmanager is not expected to return to service before the next new production periodturnover (final job stream and JnextPlan job). For UNIX, use forward slashes inpath names.1. Use the conman stop function to stop Tivoli Workload Scheduler on the

master domain manager and its backup.2. If you copied the Security file from the master domain manager to the

backup master domain manager with a suffix, now delete the backup masterdomain manager's own Security file and rename the Security file with thesuffix as just Security.

3. If you copied the localopts file from the master domain manager to thebackup master domain manager with a suffix, now merge the backup masterdomain manager's own localopts file with the localopts file from the masterdomain manager. Look at each property in turn and determine which versionyou want to keep on what is going to be your new master domain manager.For example, the property thiscpu needs to be the one from the backup masterdomain manager, but the options for controlling how the processes run can betaken from the master domain manager.


4. On the backup master domain manager cancel the final job stream in theSymphony file (it refers to the next production period's JnextPlan on the oldmaster domain manager).

5. On the backup master domain manager, use composer to modify anyimportant job streams that run on the master domain manager, in particularthe final job stream. For each of these, change the workstation name to thename of the backup.

6. Change the workstation definition of the master domain manager frommanager to fault-tolerant agent.

7. Change the workstation definition of the backup master domain managerfrom fault-tolerant agent to manager.

Note: These two steps must be done in the order given, as the system will notallow you to have two managers at the same time.

8. On the backup master domain manager, edit the <TWA_home>/TWS/mozart/globalopts file and change the master option to the name of the backupmaster domain manager workstation (this is used mainly for reportsproduction)

9. Use the conman switchmgr function to switch to the backup master domainmanager. See “Switching a domain manager” on page 270.

10. Submit a new final job stream to the new master domain manager (old backupmaster domain manager).

11. Run JnextPlan on the new master domain manager to generate the newSymphony file.

12. Remember to log on to the backup master domain manager when opening theDynamic Workload Console, first defining a new engine to access it.

13. If the old master domain manager has failed or is being replaced, you cannow delete its workstation definition and remove it from the network.

Switching a master domain manager or dynamic domainmanager

Switching a master domain manager or dynamic domain manager affects therunning dynamic workload broker server.

The installation of a master domain manager or dynamic domain manager and ofits backup workstations includes also the installation of a dynamic workloadbroker server.

Before you switch your master domain manager or dynamic domain manager to abackup workstation, you must stop the dynamic workload broker server. After theswitch has completed, you must start the dynamic workload broker server on thenew master domain manager or dynamic domain manager. The process is notautomatic and you must ensure that you avoid having two concurrently activeservers.

If you have to switch the master domain manager or dynamic domain managerbecause the system running the current workstation failed, make sure that also thedynamic workload broker server is down, in which case, you only need to start thenew dynamic workload broker server after switching the master.

If you switch the master domain manager or dynamic domain manager for anyother reason than a system failure, and you are switching to a backup workstationwhile the system running the current master domain manager or dynamic domain


|

|

||

|||

||||||

||||

|||

manager is up, you risk having two concurrently active servers. This is why it isimportant that you stop the current dynamic workload broker server before youswitch, and that you start the new instance after the backup workstation takesover.

Here is the procedure to follow every time you switch the master domain manageror dynamic domain manager if you run dynamic scheduling in your network:1. If the dynamic workload broker server on the current master domain manager

or dynamic domain manager is still running, stop it. Use wastoolstopBrokerApplication.sh on UNIX and Linux or stopBrokerApplication.baton Windows as follows:stopBrokerApplication -user username -password password [-port portnumber]


2. Switch the master domain manager or dynamic domain manager to a backupworkstation. Use either the conman switchmgr command or the DynamicWorkload Console. For more information, see the section about the switchmgrcommand in Tivoli Workload Scheduler: User's Guide and Reference.

3. Start the dynamic workload broker server running with the new workstation.Use wastool startBrokerApplication.sh on UNIX and Linux orstartBrokerApplication.bat on Windows as follows:startBrokerApplication -user username -password password [-port portnumber]


Changing key Tivoli Workload Scheduler passwords

When you change passwords for key users in your Tivoli Workload Schedulerenvironment, there are various operations to perform, depending on which user'spassword is being changed, the type of operating system on which it is deployed,and the type of Tivoli Workload Scheduler node where the password is beingchanged. You can perform these operations manually, or you can use thechangePassword script described in “Using the changePassword script” on page282 to accomplish the necessary operations automatically.

If you decide to proceed manually, the following pages describe what you have todo if the passwords of any of the following users change:

Tivoli Workload Scheduler instance ownerThe <TWS_user> (the instance owner) of a Tivoli Workload Schedulercomponent (on Windows only).

WebSphere Application Server userThe WebSphere Application Server user (as identified by the WebSphereApplication Server tools) which authenticates the <TWS_user> being usedby Tivoli Workload Scheduler components.

The database user (J2C) of a Tivoli Workload Scheduler component:

DB2 If you are using a DB2 database, this is the user ID used to accessDB2.

Note: This is different according to whether you have the server orthe client installed:


||||

||

||||

|

||

||||

|||

|

||

DB2 Server installedThe DB2 administration user (local) is used.

DB2 Client installedThe Tivoli Workload Scheduler DB2 user on theremote server is used.

Oracle If you are using an Oracle database, the Oracle schema owner user.

Note: The Oracle schema owner is not an operating system ID.Even if it has the same value as an operating system ID onthe same computer, it is completely separate, and thepasswords are changed separately.

Streamlogon userThe streamlogon user of any job run in the Tivoli WorkloadScheduler environment (jobs running on Windows only)

For all other users of Tivoli Workload Scheduler, no action is required if theirpasswords change.

If you use the changePassword script, the password changes and correspondingoperations are performed automatically. For detailed information about the script,refer to “Using the changePassword script” on page 282. If you decide to proceedmanually, consult Table 58 to determine if a change of password requires actions tobe taken for a role on the different Tivoli Workload Scheduler components. Lookup the role and the component and determine from the corresponding table cellwhere the changes must be made:v If the cell contains a "U", make the change on the system where the indicated

component is runningv If the cell contains "MDM", make the change on the master domain manager to

which the component belongs

Table 58. If and where password changes are required

Role MDM BKM FTAFTA +CONN

Tivoli Workload Scheduler instanceowner (Windows)

U U U U

WebSphere Application Server user U U U

Database user U U

Streamlogon user (Windows) U U MDM MDM

For example, if you are the TWS_user (the instance owner) of a fault-tolerantagent, you need to implement the password change on the system where thefault-tolerant agent is installed, but if you are also the streamlogon user of jobsrunning on that system, the changes required for the new password must beapplied at the master domain manager to which the fault-tolerant agent belongs.

If you are not certain which user role you are playing, consult “Determining therole of the user whose password has changed” on page 276.

When you have determined what role you are playing, determine if you need totake any actions, and if so, where, by consulting “Determining the actions to take”on page 277.


Determining the role of the user whose password haschanged

Use the following procedure to determine which role or roles the user whosepassword has changed is playing.

Attention: A user might have more than one role, in which case you must followmore than on procedure to change the password

1. Check if the user is the Tivoli Workload Scheduler instance owner:

WindowsCheck if the user whose password is to be changed is the user thatowns the Tivoli Workload Scheduler for <TWS_user> service.

UNIX Run the following command:ps -ef | grep netman

If the user whose password has changed matches the user ID revealed bythe above, the user is the Tivoli Workload Scheduler instance owner.

2. Check if the user is the WebSphere Application Server user or the databaseuser, or both:

1. Log on to the computer where Tivoli Workload Scheduler is installed asthe following user:

UNIX root


2. Access the directory: <TWA_home>/wastools3. From that same directory run the following script:

UNIX showSecurityProperties.sh > <output_file.txt>

WindowsshowSecurityProperties.bat > <output_file.txt>

Note: This command might display a message from the applicationserver (WASX7357I:) in the output file. You can ignore thismessage.

4. Open <output_file.txt> in a text editor.5. Check the value of the key: activeUserRegistry. Depending on the

value, check if the user whose password has changed is one of the IDkeys:

Table 59. Values of activeUserRegistry to check

Value of activeUserRegistrykey: User ID key to check: Password to change

LocalOS LocalOSServerID LocalOSServerpassword

LDAP LDAPServerid LDAPPassword

If the user whose password has changed matches the appropriate IDkey, the user is the WebSphere Application Server user

6. Check the value of the key j2cUserid . If the user whose password isto be changed matches this key, the user is the database user.


Note: If the user is the Oracle schema owner, the password must alsobe changed within Oracle (see the Oracle documentation).

3. Check if the user is a streamlogon userUsing composer or the Dynamic Workload Console, check if the user isidentified as a Windows user. If so, the user is a streamlogon user.

When you have determined which roles the user plays, see Table 58 on page 275 todetermine if and where the password change must be implemented, and then“Determining the actions to take.”

Determining the actions to takeConsult Table 60 to determine which actions you need to perform for a change ofpassword:

Table 60. Password change actions

TWS instanceowner

(Windows only)

WebSphereApplicationServer user Database user

Streamlogonuser (Windowsonly)

“Action 1 - change the WebSphereApplication Server user ID password” onpage 278

U (1)

“Action 2 - change password used bycommand-line clients to access the masterdomain manager” on page 279

U

“Action 3 - change password used byfault-tolerant agent systems to access themaster domain manager (for conman)” onpage 279

U

“Action 4 - update the engine connectionparameters in the GUIs” on page 280

U

“Action 5 - change the j2c user IDpassword” on page 280

U (1)

“Action 6 - update SOAP properties” onpage 281

U

The following step only applies to passwords of users on Windows computers

“Action 7 - Windows - update Windowsservices” on page 281

U U

“Action 8 - change the Tivoli WorkloadScheduler Windows user definition” on page281

U

Note:

1. If the user is both the WebSphere Application Server user and thedatabase user, the changes made by running changeSecurityPropertiescan be performed as one action, modifying both passwords with thesame value.


Action 1 - change the WebSphere Application Server user IDpassword

Use the changeSecurityProperties utility to change the WebSphere ApplicationServer user ID password.

The procedure requires you to create a text file of the current security properties,edit the file, stop the application server, run the utility and restart the applicationserver.

Note: You might have already created the text file while determining your role(see “Determining the role of the user whose password has changed” onpage 276).

Find information about how to do this as follows:v “Application server - using the utilities that change the properties” on page 312

gives a generic description of the procedure for making any change to theWebSphere Application Server properties

v “Changing the security settings” on page 296 gives reference information aboutthe utility

v When editing the text file of the current security properties, Locate eitherLocalOSServerpassword or LDAPPassword, depending on the type ofauthentication you are using (see Table 59 on page 276), and change thepassword to the new value, in plain text.

Note:

1. If the user is both the WebSphere Application Server user and thedatabase user, you can change the properties for both in the same action.See “Action 5 - change the j2c user ID password” on page 280. for detailsof the property to change.

2. The changeSecurityProperties utility might display a message from theapplication server (WASX7357I:). You can ignore this message.

3. When you supply a password in a text file forchangeSecurityProperties, there is a small security exposure. When youenter a password in the file, the password is entered in clear(unencrypted). After you have run changeSecurityProperties, thepassword remains in clear in the text file you have edited, but if you runshowSecurityProperties the password is output encrypted. Thus, yourpotential security exposure is limited to the time from when you enteredthe password in the text file until when you manually deleted the textfile after using changeSecurityProperties.


Attention: if you subsequently want to change other parameters and donot want to change any passwords, you must do one of the followingbefore running changeSecurityProperties:v Resupply the passwords in clearv Comment the password propertiesv Delete the password properties

This is to avoid that the row of asterisks is applied as the password.

Note that if you run showSecurityProperties and see that any passwordin the encrypted form is shown as a sequence of 5 asterisks (*), this iswrong. A maximum of 3 asterisks is supported. Sequences of 5 asterisksare not supported and your passwords, encrypted as such, are ignored.If this happens, reset the password to a shorter one.

Action 2 - change password used by command-line clients toaccess the master domain manager

If you have changed the password of the WebSphere Application Server user thatcommand-line clients use to connect to the master domain manager, the connectionparameters must be updated.

Follow this procedure:1. Identify all systems that have a command line client remote connection defined

with the master domain manager2. On these workstations, open the user options files (one for each user). The

default file name is <User_home>/.TWS/useropts, but if you have more than oneinstance of Tivoli Workload Scheduler on a system, you might haveimplemented separate user options files to make separate connections, in whichcase consult the useropts key in the localopts file on each instance to determinethe name of the specific useropts file for that instance.

3. For each file, locate the password key (encrypted) and change its value to thatof the new password in plain text, enclosed in double quotes. The password issaved in clear, but will be encrypted at first logon of the User ID.

4. Save the files.5. Check if the following file exists: <Root_home>/.TWS/useropts. If it does, change

the password in the same way.

Action 3 - change password used by fault-tolerant agentsystems to access the master domain manager (for conman)

If you have changed the password of the WebSphere Application Server user thatis used by fault-tolerant agents with an HTTP or HTTPS connection defined in thelocal options that points to the master domain manager, the connection parametersmust be updated.

Follow this procedure:1. Identify all fault-tolerant agents with an HTTP or HTTPS connection defined in

the local options that points to the master domain manager.2. On these workstations, open the user options file <Root_home>/.TWS/useropts


3. Locate the password key (encrypted) and change its value to that of the newpassword in plain text, enclosed in double quotes. The password is saved inclear, but will be encrypted at first logon of the User ID.

4. Save the file.

Action 4 - update the engine connection parameters in theGUIs

If you have changed the password of the WebSphere Application Server user thatis used by the Dynamic Workload Console to connect to the distributed engine, theengine connection parameters must be updated, as follows:1. On each instance of the Dynamic Workload Console locate the page where you

modify the distributed engine connection parameters2. Change the password and submit the page.

Action 5 - change the j2c user ID password

Use the changeSecurityProperties utility to change the j2c database user IDpassword.

The procedure requires you to create a text file of the current security properties,edit the file, stop the application server, run the utility and restart the applicationserver.

Note: You might have already created the text file while determining your role(see “Determining the role of the user whose password has changed” onpage 276).

Find information about how to do this as follows:v “Application server - using the utilities that change the properties” on page 312


v “Changing the security settings” on page 296 gives reference information aboutthe utility

v When editing the text file of the current security properties, Locate thej2cPassword and change the password to the new value, in plain text.

Note:

1. If the user is both the WebSphere Application Server user and thedatabase user, you can change the properties for both in the same action.See “Action 1 - change the WebSphere Application Server user IDpassword” on page 278. for details of the property to change.

2. The changeSecurityProperties utility might display a message from theapplication server (WASX7357I:). You can ignore this message.

3. When you supply a password in a text file forchangeSecurityProperties, there is a small security exposure. When youenter a password in the file, the password is entered in clear(unencrypted). After you have run changeSecurityProperties, thepassword remains in clear in the text file you have edited, but if you runshowSecurityProperties the password is output encrypted. Thus, yourpotential security exposure is limited to the time from when you enteredthe password in the text file until when you manually deleted the textfile after using changeSecurityProperties.


Attention: if you subsequently want to change other parameters and donot want to change any passwords, you must do one of the followingbefore running changeSecurityProperties:v Resupply the passwords in clearv Comment the password propertiesv Delete the password properties


Action 6 - update SOAP properties

After the password of the WebSphere Application Server administration user hasbeen modified, it is important to change the SOAP client properties using theupdateWas.sh/.bat script (see “Application server - updating the SOAP propertiesafter changing the WebSphere Application Server user or its password” on page306 for full details). For example:updateWas.sh -user [email protected] -password zzzz

where theuser and password options are the user that is authorized to stop theWebSphere Application Server.

Stop and restart WebSphere Application Server using the stopappserver andstartappserver commands to make the change effective.

Action 7 - Windows - update Windows services

On Windows, the <TWS_user> account is used to start the following services:v Tivoli Token Service for <TWS_user>

v Tivoli Workload Scheduler for <TWS_user>

v IBM WebSphere Application Server V7.0 - <TWS_user>.

The password must be updated in the properties of these services, or they are notable to start at next reboot. This is done as follows:1. Stop all Tivoli Workload Scheduler processes. See “Unlinking and stopping

Tivoli Workload Scheduler” on page 283 for details.2. Locate the script updateWasService.bat in the <TWA_home>/wastools directory.3. Run updateWasService.bat, as described in “Application server - updating the

Windows services after modifications” on page 305, giving the new passwordas the <WAS_user_password>.

4. Restart all Tivoli Workload Scheduler processes using the StartUp command.

Action 8 - change the Tivoli Workload Scheduler Windowsuser definition

If the user ID is used within Tivoli Workload Scheduler to run jobs, follow thisprocedure:1. Run the composer modify user command. The user details of the selected user

are written to a temporary file, which is opened.2. Edit the password field so that it contains the new password value delimited

by double quote characters (").3. Save the file, and the contents are added to the database.


4. To make the change immediately effective in the current plan, issue the conmanaltpass command.

For the full syntax of these commands see the Tivoli Workload Scheduler: User'sGuide and Reference.

Using the changePassword script

Use the changePassword script from the <TWA_home>/wastools directory to changethe passwords of any of the following users:v Tivoli Workload Scheduler instance owner (<TWS_user>)v WebSphere Application Server userv Database (J2C) user for either Oracle or DB2v Streamlogon user (Windows only)

If required, the script performs the necessary changes to the useropts file and stopsand restarts the WebSphere Application Server. You can run this script from yourmaster domain manager or Tivoli Workload Scheduler agent. The script determinesthe role of the users for which the password must be changed and performs thechecks and actions of the manual procedure described in actions 1 through 8. Runthe script as follows:

UNIXchangePassword.sh -user <USERID>

-password <PASSWORD>[-wasuser <WASUSER>][-waspassword <WASPASSWORD>][-usroptshome <HOMEDIR>]

Where the arguments are as follows:

–user <USERID>This argument is mandatory. Specify the user whose password youare changing.

–password <PASSWORD>This argument is mandatory. Specify the new password for theuser.

–wasuser <WASUSER>This argument is optional. Specify the WebSphere ApplicationServer user. By default, the <USERID> value is used.

–waspassword <WASPASSWORD>This argument is optional. Specify the WebSphere ApplicationServer user password. By default, the <PASSWORD> value is used.The <WASUSER> and <WASPASSWORD> values are ignored if theWebSphere Application Server is not present on this instance or ifthe script is running for a Tivoli Workload Scheduler instance.

–usroptshome<HOMEDIR>This argument is optional. The script searches for the USEROPTS filein the TWA_home/.TWSWebSphere Application Server directory. Thisargument is ignored if the script is not running for a TivoliWorkload Scheduler instance.

WindowschangePassword.bat -user <USERID>

-password <PASSWORD>[-srvuser <SRVUSERID>]


[-srvpassword <SRVPASSWORD>][-wasuser <WASUSERID>][-waspassword <WASPASSWORD>][-usroptshome <HOMEDIR>][-streamlogonws <WS>][-streamlogondm <DOMAIN>]

Where the arguments are as follows:

–user <USERID>This argument is mandatory. Specify the user whose password you arechanging.

–password <PASSWORD>This argument is mandatory. Specify the new password for the user.

–srvuser <SRVUSERID>This argument is optional. Specify the Windows service user. If you arerunning the script for a Tivoli Workload Scheduler instance, the valuespecified here is the same as the Tivoli Workload Scheduler user. Bydefault, the <USERID> value is used.

–srvpassword <SRVPASSWORD>This argument is optional. The password of the Windows service user. Bydefault, the <PASSWORD> value is used.

–wasuser <WASUSER>This argument is optional. Specify the WebSphere Application Server user.By default, the <USERID> value is used.

–waspassword <WASPASSWORD>This argument is optional. Specify the WebSphere Application Server userpassword. By default, the <PASSWORD> value is used. The <WASUSER>and <WASPASSWORD> values are ignored if the WebSphere ApplicationServer is not present on this instance or if the script is running for a TivoliWorkload Scheduler instance.

–usroptshome<HOMEDIR>This argument is optional. The script searches for the USEROPTS file in theTWA_home/.TWSWebSphere Application Server directory. By default, thehome directory of the user running the script is used.

–streamlogonws<WS>This argument is optional. The script updates the Windows user definitionfor the <WS>#<DOMAIN>/<USER> user in the Tivoli Workload Schedulerdatabase. By default, the Windows user definition for the <USER> isupdated. The update is performed only if the tool is running on the masterdomain manager in a Windows environment.

–streamlogondm<DOMAIN>This argument is optional. Specify the domain of the user specified for the<USER>.

Unlinking and stopping Tivoli Workload Scheduler

Before you perform an upgrade or uninstall, install a fix pack, or performmaintenance activities, ensure that all Tivoli Workload Scheduler processes andservices are stopped. Follow these steps:1. If you have jobs that are currently running on the workstation, wait for them to

finish. To determine which are not finished, check for jobs that are in the exec


state. When there are no jobs in this state, and you have allowed sufficient timefor all events to be distributed in your network, you can continue with the restof the procedure.

2. If the workstation that you want to stop is not the master domain manager,unlink the workstation by issuing the following command from the commandline of the master domain manager:conman "unlink workstationname;noask"

3. All Tivoli Workload Scheduler processes on the workstation must then bestopped manually. From the command line, while logged on as the<TWS_user>, use the following command:conman “stop;wait”

4. From the command line, stop the netman process as follows:

UNIX Run:conman “shut"

Note: Do not use the UNIX kill command to stop Tivoli WorkloadScheduler processes.

WindowsRun the shutdown.cmd command from the Tivoli Workload Schedulerhome directory.

5. If the workstation is at V8.4 or higher, stop the SSM agent, as follows:v On Windows, stop the Windows service: Tivoli Workload Scheduler SSM

Agent (for <TWS_user>).v On UNIX, run stopmon.

6. If you are updating an agent, remove (unmount) any NFS mounted directoriesfrom the master domain manager.

7. If you are upgrading an installation that includes the connector, stop theconnector.

8. Stop the WebSphere Application Server using the conman stopappservercommand (see “Starting and stopping the application server and appservman”on page 303)

To verify if there are services and processes still running, complete the followingsteps:

UNIX Type the command:ps -u <TWS_user>

Verify that the following processes are not running: netman, mailman,batchman, writer, jobman, JOBMAN, stageman, logman, planman,monman, ssmagent.bin, and appservman.

WindowsRun Task Manager, and verify that the following processes are notrunning: netman, mailman, batchman, writer, jobman, stageman, JOBMON,tokensrv, batchup, logman, planman, monman, ssmagent, and appservman.

Also, ensure that no system programs are accessing the directory orsubdirectories, including the command prompt and Windows Explorer.


Changing the database host name, port, or database nameTo change the database host name, port, or database name, the procedure differs,depending on whether the database is on DB2 or Oracle:v “Change the DB2 host name, port, or database name”v “Changing the Oracle host name, port, or database name” on page 291

Change the DB2 host name, port, or database name

If you need to change the DB2 host name, port, or database name, use thechangeDataSourceProperties utility to reflect these changes in the applicationserver on the master domain manager.

When you installed Tivoli Workload Scheduler, the default database name that wasused for the creation of the database was TWS (which you might have changed).You also supplied the port and the host name of the DB2 server. If you want tochange any of these details, you must do the following:1. Stop DB2 and Tivoli Workload Scheduler2. Use the facilities of DB2 (see DB2 documentation for details) or the operating

system to change the database name, port or host name.3. Change the configuration of the Tivoli Workload Scheduler application server

so that it points correctly to the changed DB2 configuration.The procedure requires you to stop the application server, create a text file ofthe current data source properties, edit the file, run the utility and restart theapplication server. Find information about how to do this as follows:v “Application server - using the utilities that change the properties” on page

312 gives a generic description of the procedure for making any change tothe WebSphere Application Server properties

v “Changing data source properties” on page 286 lists all the data sourceproperties and gives other reference information about the utility

v When editing the text file of the current data source properties:a. Edit the text file and locate the following properties:

################################################################# DB2 Type4 Resource Properties################################################################DB2Type4DatabaseName=TWSDB2Type4ServerName=localhostDB2Type4PortNumber=50083

b. Set the following entries:

DB2Type4DatabaseNameThe new name of the Tivoli Workload Scheduler database.

DB2Type4ServerNameThe new DB2 server host name.

DB2Type4PortNumberThe new DB2 server port.

When you change a DB2 server port, you must also modify theconfiguration of the node where the Tivoli Workload Scheduler wascataloged:– If you are working with a DB2 client, open a command line session

and log in as DB2 Administrator, then run the following commands:


|||

||

DB2 CLIENTdb2 uncatalog node <TWSDBNAME>_NDdb2 catalog tcpip node <TWSDBNAME>_ND remote <HOSTNAME>server <NEWPORT>

– If you are working with a DB2 server, open a command line sessionand log in as DB2 Administrator, then run the following commands :DB2 SERVERdb2 uncatalog node LBNODEdb2 catalog tcpip node LBNODE remote 127.0.0.1 server <NEWPORT>

Do not change any other properties.

Note: The utility might display a message from the application server(WASX7357I:). You can ignore this message.

4. Start DB2 and Tivoli Workload Scheduler.

This script can also be used to change other data source properties. However, ifyou do so, Tivoli Workload Scheduler might not work correctly. You are advised tomake any other changes only under the instructions of IBM Software Support, tocorrect specific problems. One of those specific problems could be the need toresolve problems with the JBDC driver, see “Resolving problems with the JDBCdriver” on page 289.

Changing data source propertiesYou run the changeDataSourceProperties script on the master domain manager tochange the data source properties of the RDBMS in use with the master domainmanager. You are required to update the data source properties in the followingcases:v You migrate your data from an Oracle database to DB2 using the reconfiguration

method.v You change the database name, server, host, or port.v You change the path to the JDBC driver of the RDBMS.

The procedure for running the script is described in detail in “Application server -using the utilities that change the properties” on page 312, but in summary you dothe following:v Run showDataSourceProperties.sh (.bat) > my_file_name to obtain the current

propertiesv Edit my_file_namev Run changeDataSourceProperties.sh (.bat) my_file_name

Note: my_file_name must be the fully qualified path of the file.

The change utility calls the wsadmin utility by runningChangeDataSourceProperties.jacl with the properties file as input.

Only the WebSphere Application Server resources.xml are affected by this script.The full path of the file is:<TWA_home>/eWAS/profiles/TIPProfile/config/cells/DefaultNode/nodes/

DefaultNode/servers/server<n>/resources.xml

The following is an example of the properties that can be changed with this utility.Only some of the options listed are currently in use by Tivoli Workload Scheduler.################################################################JDBC Path Variables################################################################


||||

||

|||

ORACLE_JDBC_DRIVER_PATH=DB2_JDBC_DRIVER_PATH=c:/ibm/sqllib/javaDB2UNIVERSAL_JDBC_DRIVER_PATH=c:/ibm/sqllib/java

################################################################DB2 Type2 Resource Properties################################################################DB2Type2JndiName=DB2Type2Description=DB2Type2ConnectionAttribute=cursorhold=0DB2Type2EnableMultithreadedAccessDetection=falseDB2Type2Reauthentication=falseDB2Type2JmsOnePhaseOptimization=falseDB2Type2DatabaseName=TWSZ_DBDB2Type2PreTestSQLString=SELECT 1 FROM SYSIBM.SYSDUMMY1

################################################################DB2 Type4 Resource Properties################################################################DB2Type4JndiName=jdbc/twsdbDB2Type4DatabaseName=TWSZDB2Type4DriverType=4DB2Type4ServerName=myhost.mydomain.comDB2Type4PortNumber=50000DB2Type4SslConnection=falseDB2Type4Description=DB2Type4TraceLevel=DB2Type4TraceFile=DB2Type4FullyMaterializeLobData=trueDB2Type4ResultSetHoldability=2DB2Type4CurrentPackageSet=DB2Type4ReadOnly=falseDB2Type4DeferPrepares=trueDB2Type4CurrentSchema=DB2Type4CliSchema=DB2Type4RetrieveMessagesFromServerOnGetMessage=trueDB2Type4ClientAccountingInformation=DB2Type4ClientApplicationInformation=DB2Type4ClientUser=DB2Type4ClientWorkstation=DB2Type4CurrentPackagePath=DB2Type4CurrentSQLID=DB2Type4KerberosServerPrincipal=DB2Type4LoginTimeout=0DB2Type4SecurityMechanism=DB2Type4TraceFileAppend=falseDB2Type4CurrentFunctionPath=DB2Type4CursorSensitivity=DB2Type4KeepDynamic=DB2Type4CurrentLockTimeout=DB2Type4EnableMultithreadedAccessDetection=falseDB2Type4Reauthentication=falseDB2Type4JmsOnePhaseOptimization=falseDB2Type4PreTestSQLString=SELECT 1 FROM SYSIBM.SYSDUMMY1DB2Type4DbFailOverEnabled=falseDB2Type4ConnRetriesDuringDBFailover=100DB2Type4ConnRetryIntervalDuringDBFailover=3000# DB2Type4IsolationLevel can be one of the following:# CURSOR_STABILITY or READ_STABILITYDB2Type4IsolationLevel=CURSOR_STABILITY

################################################################Oracle Type2 Resource Properties################################################################


OracleType2JndiName=OracleType2DriverType=OracleType2URL=jdbc:oracle:oci:@ORCLOracleType2DatabaseName=OracleType2ServerName=OracleType2PortNumber=1521OracleType2OracleLogFileSizeLimit=0OracleType2OracleLogFileCount=1OracleType2OracleLogFileName=OracleType2OracleLogTraceLevel=INFOOracleType2OracleLogFormat=SimpleFormatOracleType2OracleLogPackageName=oracle.jdbc.driverOracleType2TNSEntryName=OracleType2NetworkProtocol=OracleType2DataSourceName=OracleType2LoginTimeout=OracleType2Description=OracleType2EnableMultithreadedAccessDetection=falseOracleType2Reauthentication=falseOracleType2JmsOnePhaseOptimization=falseOracleType2PreTestSQLString=SELECT 1 FROM DUALOracleType2DbFailOverEnabled=falseOracleType2ConnRetriesDuringDBFailover=100OracleType2ConnRetryIntervalDuringDBFailover=3000

################################################################Oracle Type4 Resource Properties################################################################OracleType4JndiName=OracleType4DriverType=OracleType4URL=jdbc:oracle:thin:@//localhost:1521/ORCLOracleType4DatabaseName=OracleType4ServerName=OracleType4PortNumber=1521OracleType4OracleLogFileSizeLimit=0OracleType4OracleLogFileCount=1OracleType4OracleLogFileName=OracleType4OracleLogTraceLevel=INFOOracleType4OracleLogFormat=SimpleFormatOracleType4OracleLogPackageName=oracle.jdbc.driverOracleType4TNSEntryName=OracleType4NetworkProtocol=OracleType4DataSourceName=OracleType4LoginTimeout=OracleType4Description=OracleType4EnableMultithreadedAccessDetection=falseOracleType4Reauthentication=falseOracleType4JmsOnePhaseOptimization=falseOracleType4PreTestSQLString=SELECT 1 FROM DUALOracleType4DbFailOverEnabled=falseOracleType4ConnRetriesDuringDBFailover=100OracleType4ConnRetryIntervalDuringDBFailover=3000

When you change data source properties, observe the following rules:v If a property is not provided in the properties file, the current value is not

changedv If a property is provided with a non-blank value, the current value is updated.v If a property is provided with a blank value, the setting is set to blank if the

property is classified as erasable or left unchanged if not.v Always use type 4 data sources for DB2 and type 2 data sources for Oracle.v Set the appropriate JDBC driver path variable for the RDBMS of your choice.


– For DB2, the JDBC driver is located in the java subfolder of the sqllibdirectory. For example:DB2_JDBC_DRIVER_PATH=c:/program files/ibm/sqllib/java

orDB2UNIVERSAL_JDBC_DRIVER_PATH=c:/program files/ibm/sqllib/java

– For Oracle, it is located in the jdbc/lib subfolder of the Oracle homedirectory. For example:ORACLE_JDBC_DRIVER_PATH=C:/Oracle/product/10.2.0/db_1/jdbc/lib

v Make sure that the data source JNDI name is always set to jdbc/twsdb in the...JndiName property of the RDBMS you use. If you change the RDBMS,proceed as follows:1. Reset to a name of your choice the ...JndiName property of the RDBMS from

which you are changing.2. Set to jdbc/twsdb the ...JndiName property of the new RDBMS.

v See that the following properties are set:– For DB2:

DB2Type4JndiNameDB2Type4DatabaseNameDB2Type4ServerNameDB2Type4PortNumber

– For Oracle:OracleType2JndiNameOracleType2DatabaseNameOracleType2ServerNameOracleType2PortNumber

Displaying the current data source properties: To display the current properties,use the following utility:

UNIX showDataSourceProperties.sh

WindowsshowDataSourceProperties.bat

Resolving problems with the JDBC driverTivoli Workload Scheduler is supplied using the JDBC driver type 4 for DB2 andtype 2 for Oracle. However, each can use the other driver type, if necessary. IBMSoftware Support might ask you to change to this driver. This section tells youhow.

Attention: This procedure must only be performed under the control of IBMSoftware Support.

To change the driver you need to change the data source properties following theprocedure described in “Changing the database host name, port, or databasename” on page 285. However, the parameters that you change are different. This isan example of the type 4 and type 2 parameters for DB2:

JDBC driver type 4 parameters################################################################# DB2 Type4 Resource Properties################################################################DB2Type4JndiName=jdbc/twsdbDB2Type4DatabaseName=TWSZDB2Type4DriverType=4DB2Type4ServerName=myhost.mydomain.comDB2Type4PortNumber=50000


DB2Type4SslConnection=falseDB2Type4Description=DB2Type4TraceLevel=DB2Type4TraceFile=DB2Type4FullyMaterializeLobData=trueDB2Type4ResultSetHoldability=2DB2Type4CurrentPackageSet=DB2Type4ReadOnly=falseDB2Type4DeferPrepares=trueDB2Type4CurrentSchema=DB2Type4CliSchema=DB2Type4RetrieveMessagesFromServerOnGetMessage=trueDB2Type4ClientAccountingInformation=DB2Type4ClientApplicationInformation=DB2Type4ClientUser=DB2Type4ClientWorkstation=DB2Type4CurrentPackagePath=DB2Type4CurrentSQLID=DB2Type4KerberosServerPrincipal=DB2Type4LoginTimeout=0DB2Type4SecurityMechanism=DB2Type4TraceFileAppend=falseDB2Type4CurrentFunctionPath=DB2Type4CursorSensitivity=DB2Type4KeepDynamic=DB2Type4CurrentLockTimeout=DB2Type4EnableMultithreadedAccessDetection=falseDB2Type4Reauthentication=falseDB2Type4JmsOnePhaseOptimization=falseDB2Type4PreTestSQLString=SELECT 1 FROM SYSIBM.SYSDUMMY1DB2Type4DbFailOverEnabled=falseDB2Type4ConnRetriesDuringDBFailover=100DB2Type4ConnRetryIntervalDuringDBFailover=3000# DB2Type4IsolationLevel can be one of the following:# CURSOR_STABILITY or READ_STABILITYDB2Type4IsolationLevel=CURSOR_STABILITY

JDBC Driver type 2 parameters################################################################# DB2 Type2 Resource Properties################################################################DB2Type2JndiName=DB2Type2Description=DB2Type2ConnectionAttribute=cursorhold=0DB2Type2EnableMultithreadedAccessDetection=falseDB2Type2Reauthentication=falseDB2Type2JmsOnePhaseOptimization=falseDB2Type2DatabaseName=TWSZ_DBDB2Type2PreTestSQLString=SELECT 1 FROM SYSIBM.SYSDUMMY1

Switching drivers or changing the JNDI name: The data source JNDI name mustbe unique. In the above examples the JNDI name for driver 4 is set to the correctvalue. To switch drivers, modify the parameters so that the values are reversed, asfollows:Example 1: default values for the JNDI name:

#DB2Type4JndiName=jdbc/twsdb

...

#DB2Type2JndiName=jdbc/twsdb2

Example 2: switched values for the JNDI name:


#DB2Type4JndiName=jdbc/twsdb2

...

#DB2Type2JndiName=jdbc/twsdb

To change the driver names to a different value, see the following:Example 3: different values for the JNDI name:

#DB2Type4JndiName=jdbc/twsdb_test4

...

#DB2Type2JndiName=jdbc/twsdb_test2

Changing the Oracle host name, port, or database name

If you need to change the Oracle host name, port, or database name, you cannormally manage the change within Oracle. This is because WebSphere ApplicationServer points at the Oracle service where these items are defined. See the Oracledocumentation for information on how to change them.

However, the properties that you are changing might be defined in<TWA_home>/eWAS/profiles/TIPProfile/properties/TWSConfig.properties. In thiscase you must ensure that they are changed here, as well. The properties inquestion are:com.ibm.tws.dao.rdbms.rdbmsName = ORACLEcom.ibm.tws.dao.rdbms.modelSchema = <TWS_Oracle_User>com.ibm.tws.dao.rdbms.eventRuleSchema = <TWS_Oracle_User>com.ibm.tws.dao.rdbms.logSchema = <TWS_Oracle_User>

Changing the workstation host name or IP addressWhen you change the host name, the IP address or both on the workstations ofyour Tivoli Workload Scheduler environment to have it function properly, youmust report the changed value on:v The WebSphere Application Server if the following components changed the

host name, the IP address or both:– Master domain manager– Backup master domain manager– Connector or z/OS connector– Dynamic Workload Console

For more information see “Reporting the changes in the WebSphere ApplicationServer configuration file” on page 292.

v The following components if the workstation where you installed the RDBMSchanged the host name, the IP address or both:– Master domain manager– Backup master domain manager– Dynamic domain manager– Backup dynamic domain manager

For more information see “Reporting the changed host name or IP address ofthe workstation where you installed the RDBMS” on page 293.

v The workstation definitions if you installed the following components:– Master domain manager– Backup master domain manager– Dynamic domain manager


|

|||

||||||

||

||||||

||

||||

– Backup dynamic domain manager– Fault-tolerant agent and standard agent– Domain manager

For more information see “Reporting the changed host name or IP address in theworkstation definition” on page 294.

Reporting the changes in the WebSphere Application Serverconfiguration file

If the following components changed the host name or IP address you must reportthe changed value in the WebSphere Application Server configuration file,performing the following steps:v Master domain managerv Backup master domain managerv Connector or z/OS connectorv Dynamic Workload Console1. Stop the WebSphere Application Server.2. Obtain the changed host name, IP address, or both.3. Run the showHostProperties tool by redirecting the output to a text file to

obtain the current properties.4. Open the file and go to the Host Configuration Panel.

Below an example of the section you have to refer to:################################################################# Host Configuration Panel################################################################# Old HostnameoldHostname=myoldhost.romelab.ibm.it.com# New HostnamenewHostname=mynewhost.romelab.ibm.it.com.....

################################################################Ports Configuration Panel################################################################bootPort=41117bootHost=myhost.mydomain.comsoapPort=41118soapHost=myhost.mydomain.comhttpPort=41115httpHost=*httpsPort=41116httpsHost=*adminPort=41123adminHost=*adminSecurePort=41124adminSecureHost=*sasPort=41119sasHost=myhost.mydomain.comcsiServerAuthPort=41120csiServerAuthHost=myhost.mydomain.comcsiMuthualAuthPort=41121csiMuthualAuthHost=myhost.mydomain.comorbPort=41122orbHost=myhost.mydomain.com

5. Verify that the value for the properties listed below were changed with theactual values:v Old Hostnamev New Hostnamev The host names for the specific port properties


|||

||

|

|

|||||||

|

|

||

|

|

|||||||||||||||||||||||||||||||

|||||

If this values are different from the actual host name or IP address values,proceed with Step 6. If this values are not changed skip the steps below.

6. Modify the values of the properties by running the changeHostProperties tool.For more information, see “Application server - changing the host name orTCP/IP ports” on page 308.

7. Restart the WebSphere Application Server if you do not need to perform theRDBMS changes. To perform the RDBMS changes, see “Reporting the changedhost name or IP address of the workstation where you installed the RDBMS.”

8. Propagate the changes to the interfaces as follows:

Address of the master domain manager changes

v On each fault-tolerant agent, dynamic agent, and standard agent youconfigured to connect to the comman command line, update the hostparameter present in the "Attributes for CLI connections" section inthe localopts file. Usually you have the host parameter defined inthe localopts file of the workstations you use to submit predefinedjobs and job streams (sbj and sbs commands).

v On every command line client, update the host parameter present inthe "Attributes for CLI connections" section in the localopts file.

v On the Dynamic Workload Console update the engine connections.

Address of the Dynamic Workload Console changesNotify all the users of the new web address.

Reporting the changed host name or IP address of theworkstation where you installed the RDBMS

If you changed the host name or IP address in the workstation where you installedthe RDBMS, contact your database administrator to reconfigure your RDBMS touse the new host name or IP address. If you are using DB2, see the proceduredescribed in https://www-304.ibm.com/support/docview.wss?uid=swg21258834.

Propagate the changes to the following components by performing the stepsbelow:v Master domain managerv Backup master domain managerv Dynamic domain managerv Backup dynamic domain manager1. Stop the WebSphere Application Server.2. Run the showDataSourceProperties tool by redirecting the output to a text file

to obtain the current properties.3. Open the file and identify the database section where the

databasetypeTypenJndiName property is equal to jdbc/twsdb.where databasetype is the database you are using, for example DB2, and n canbe 2 or 4.Below an example of the section you have to refer to if you are using DB2:################################################################DB2 Type4 Resource Properties################################################################DB2Type4JndiName=jdbc/twsdbDB2Type4DatabaseName=TWSZDB2Type4DriverType=4DB2Type4ServerName=myhost.mydomain.com.....


||

|||

|||

|

|

||||||

||

|

||

|

|

||||

||||||

|

||

||

||

|

||||||||

https://www.ibm.com/support/docview.wss?uid=swg21258834

4. Verify the value of the databasetypeTypenServerName property. If this value ischanged proceed with Step 5. If this value is not changed skip the steps below.

5. Modify the databasetypeTypenServerName=value property by runningchangeDataSourceProperties. For more information, see “Changing thedatabase host name, port, or database name” on page 285.

6. To use the:

Dynamic Workload Console reportsUpdate the database connections.

Command line reportsUpdate the following section of the <report_home>\config\common.properties file####################################################################### DATABASE PROPERTIES####################################################################### Specify the host name or TCP/IP address of the database,# its port number and name.DatabaseHostname=<hostname>DatabasePort=50000DatabaseName=TWS........................

Where <report_home> is the directory where you extract the package.7. Restart the WebSphere Application Server.

Reporting the changed host name or IP address in theworkstation definition

Run this procedure if you changed the host name or IP address on the followingcomponents:v Master domain managerv Backup master domain managerv Fault-tolerant agent and standard agentv Domain manager

To modify the host name or the IP address on the workstation definition, performthe following steps:1. Use composer or the Dynamic Workload Console to check the workstation

definition stored in the database for the Tivoli Workload Scheduler instanceinstalled on the workstation where the IP address or the host name changed.

2. Verify the node attribute contains the new host name or IP address. If thisvalue is changed proceed with Step 3. If this value is not changed skip thesteps below.

3. Change the value of the node parameter with the new value.4. Refresh the new workstation definition into the plan. Do it immediately if you

are changing the host name or the IP address of a master domain manager or adomain manager. If you are changing them on a workstation that is not amaster domain manager or a domain manager you can wait the next scheduledplan generation to refresh your workstation definition in the Symphony file. Inthis case during this production day you cannot run jobs on this workstation.To generate the plan, perform the following steps:a. Run optman ls and take note of the actual value of the enCarryForward

parameter.


||

|||

|

||

|||

|||||||||

|

|

|

|

||||||

||

|||

|||

|

|||||||

||

b. If this value is not set to all, runoptman chg cf=ALL

to set it to all

c. Add the new workstation definition to the plan, by running:JnextPlan –for 0000

d. Reassign the original value to the enCarryForward parameter.

Reporting the changed host name or IP address of thedynamic workload broker server

The dynamic workload broker server is a component that Tivoli WorkloadScheduler installs when you install the following components:v Master domain managerv Backup master domain managerv Dynamic domain managerv Backup dynamic domain manager

If you changed the host name or the IP address on the dynamic workload brokerserver, or if you installed a new one run the procedure described in “Reporting thechanges in the WebSphere Application Server configuration file” on page 292.

If you changed the host name or the IP address on a master domain manager orbackup master domain manager and you ran the “Reporting the changes in theWebSphere Application Server configuration file” on page 292 procedure, skip thissection.

If you changed the host name or the IP address on the dynamic domain manageror backup dynamic domain manager you do not need to change the definition ofyour broker workstation (type broker), because the value of the node attribute isset to the localhost value to allow to switch between the dynamic workload brokerserver and its backup.

After you ran the procedure, propagate the changes to the dynamic agent andupdate the ResourceAdvisorURL property in the JobManager.ini file on eachagent connected to that dynamic workload broker server, by performing thefollowing steps:1. Run the following command to stop the agent:

ShutDownLwa

2. Edit the JobManager.ini file and change the host name or the IP address in theResourceAdvisorURL property.

3. Run the following command to start the agent:StartUpLwa

Perform the following changes:1. Open the JobDispatcherConfig.properties file and change the value of the

JDURL=https://host_name property to reflect the new host name or IP address.2. Open the CliConfig.properties file and change the value of the

ITDWBServerHost=/host_name property to reflect the new host name or IPaddress.

3. Open the ResourceAdvisorConfig.properties file and change the value of theResourceAdvisorURL=https://host_name property to reflect the new host nameor IP address.


|

|

|

|

|

|

|

|

||||||

|||

||||

|||||

||||

|

|

||

|

|

|

||

|||

|||

4. From the <TWA_home>/TDWB/bin directory, run the following command:

On Windows operating systems:exportserverdata.bat

On UNIX and Linux operating systems:exportserverdata.sh

This command extracts a list of URIs (Uniform Resource Identifier) of all thedynamic workload broker instances from the Tivoli Workload Schedulerdatabase and copies them to a temporary file. By default, the list of URIs issaved to the server.properties file, located in the current directory.

5. Change all the entries that contain the old host name to reflect the new hostname.

6. Place the file back in the database, by running the following command:

On Windows operating systems:importserverdata.bat

On UNIX and Linux operating systems:importserverdata.sh

7. Stop the dynamic workload broker, by running the following command:StopBrokerApplication

8. Start the dynamic workload broker, by running the following command:StartBrokerApplication

Reporting the changed host name or IP address of thedynamic agent

If you changed the host name or the IP address on the workstation where youinstalled the dynamic agent, the changes are automatically reported stopping andstarting the agent using the following commands:1. To stop the agent:

ShutDownLwa

2. To start the agent:StartUpLwa

Note: Do not modify manually the value of the node parameter in the dynamicagent workstation definition.

Changing the security settings

This section describes how to modify the security settings of Tivoli WorkloadScheduler. It has the following topics:

Use the changeSecurityProperties script to change various security settings on theapplication server. Those relating to SSL are described in Chapter 7, “Settingconnection security,” on page 183. Those relating to the passwords of the databaseaccess users are described in “Changing key Tivoli Workload Schedulerpasswords” on page 274. Other items, such as the active user registry and the localoperating system ID and password, can also be changed.

The procedure requires you to stop the application server, create a text file of thecurrent security properties, edit the file, run the utility and restart the applicationserver. Find information about how to do this as follows:


|

||

||

||||

||

|

||

||

|

|

|

|

|

|

|||

|

|

|

|

||

|

v “Application server - using the utilities that change the properties” on page 312gives a generic description of the procedure for making any change to theWebSphere Application Server properties

v To determine which properties need to be changed see the following topics:– Chapter 5, “Configuring authentication,” on page 139, for information about

which properties to change to modify your user registry configuration foruser authentication

– “Interface communication” on page 192, for information about whichproperties to change to configure SSL communication between the differentinterfaces and the Tivoli Workload Scheduler engine

– “Migrating data from DB2 to Oracle and vice versa” on page 233, forinformation about which properties to change when migrating your databasefrom one database platform to another

– “Changing key Tivoli Workload Scheduler passwords” on page 274, forinformation on how to use the properties to determine the required procedurefor changing key passwords

v When editing the text file of the current security properties, do as follows:1. Edit the text file and locate the properties you need to change2. Make any changes to these properties that are necessary.

Do not change any other properties.

Note:

1. The utility might display a message from the application server(WASX7357I:). You can ignore this message.

2. When you supply a password in a text file forchangeSecurityProperties, there is a small security exposure. Whenyou enter a password in the file, the password is entered in clear(unencrypted). After you have run changeSecurityProperties, thepassword remains in clear in the text file you have edited, but if yourun showSecurityProperties the password is output encrypted, as arow of asterisks. Thus, your potential security exposure is limited tothe time from when you entered the password in the text file untilwhen you manually deleted the text file after usingchangeSecurityProperties.Attention: if you want to change parameters other than passwords,and do not want to change a password, you must do one of thefollowing before running changeSecurityProperties:– Resupply the passwords in clear– Comment the password properties– Delete the password properties


Managing the event processor

The only maintenance issue for the event processor is the management of the EIFevent queue, cache.dat. The event queue is circular, with events being added atthe end and removed from the beginning. However, if there is no room to write anevent at the end of the queue it is written at the beginning, overwriting the eventat the beginning of the queue.

To increase the size of the event processor queue, follow this procedure:


1. At the workstation running the event processor, locate the file:<TWA_home>/eWAS/profiles/TIPProfile/temp/TWS/EIFListener/eif.templ

2. Edit the file and locate the keyword:BufEvtMaxSize

3. Increase the value of this keyword, according to your requirements.4. Stop and restart the WebSphere Application Server using the conman

stopappserver and conman startappserver commands (see “Starting andstopping the application server and appservman” on page 303).

Starting, stopping, and displaying dynamic workload broker status

To start or stop dynamic workload broker, use the startBrokerApplication orstopBrokerApplication commands on the active master domain manager. Sincethese commands are processed asynchronously, the brokerApplicationStatuscommand allows you to check the status of dynamic workload broker following astart or a stop. Ensure that WebSphere Application Server is running and proceedas follows:

Starting dynamic workload brokerUse startBrokerApplication.sh on UNIX and Linux orstartBrokerApplication.bat on Windows as follows:

startBrokerApplication -user username -password password [-portportnumber]

where username and password are the credentials used during theinstallation. The parameter portnumber is optional. If it is not defined, thedefault is used.

Stopping dynamic workload broker

1. Use stopBrokerApplication.sh on UNIX and Linux orstopBrokerApplication.bat on Windows as follows:stopBrokerApplication -user username -password password [-portportnumber]where username and password are the credentials used during theinstallation. The parameter portnumber is optional. If it is not defined,the default is used.

2. Run the link command. If you do not run this command, the dynamicworkload broker server is automatically linked ten minutes after thestop operation.

Displaying dynamic workload broker statusUse brokerApplicationStatus.sh on UNIX and Linux orbrokerApplicationStatus.bat on Windows as follows:

brokerApplicationStatus -user username -password password [-portportnumber]

where username and password are the credentials used during theinstallation. The parameter portnumber is optional. If it is not defined, thedefault is used.


||

||

|||

|||

Automatically initializing Tivoli Workload Scheduler instances

On UNIX systems, you can ensure that your Tivoli Workload Scheduler instancesare automatically initialized during operating system startup by adding a TivoliWorkload Scheduler service to the init process of your operating system. To do so,you can use the sample start script twa_initd located in TWA_home/config andadd it to the appropriate run level after customizing it as necessary.

Perform the following steps:1. Copy, rename, and edit the twa_initd script based on your requirements.

Provide the following information, depending on the operating system you use:

Required-StartOn Linux systems, specify the precondition services

Default-StartOn Linux systems, specify the required runlevels. For example, specifyrunlevels 2, 3, and 5.

TWS_HOMEOn all Supported UNIX systems, specify the fully qualified path to theTivoli Workload Scheduler instance you want to start.

2. Save the edited file to the appropriate system-dependent folder, as follows:

Supported Linux operating systemsSave the script in the /etc/init.d folder and register the service usingthe insserv -v script_name command.

Supported AIX operating systemsCopy the script to the appropriate rcrunlevel.d folder. Rename the scriptaccording to the runlevel script definition. For example,Ssequence_numberservice_name, as in S10tws860ma.

Supported Solaris operating systemsSave the script in the /etc/init.d folder and link the script to anappropriate file in the rcrunlevel.d folder. For example,Ssequence_numberservice_name, as in S10tws860ma.

Supported HP-UX operating systemsSave the script in the /sbin/init.d folder and link the script to anappropriate file in the rcrunlevel.d folder. or example,Ssequence_numberservice_name, as in S10tws860ma.

For more information about the inittab, init.d, insserv , and init commands, seethe reference documentation for you operating system.

The following example shows a customized script:#!/bin/sh##################################################################### Licensed Materials - Property of IBM# Restricted Materials of IBM# 5698-WSH# (C) Copyright IBM Corp. 1998, 2011 All Rights Reserved.# US Government Users Restricted Rights - Use, duplication or# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.###################################################################

### BEGIN INIT INFO# Provides: tws860ma# Required-Start: network


|

|||||

|

||

||

|||

|||

|

|||

||||

||||

||||

||

|

|||||||||||||

# Default-Start: 2 3 5# Description: TWS service### END INIT INFO

# Specify the fully qualified path name of the TWS Installation to start#TWS_HOME=/opt/IBM/TWA/TWS

TWS_START_SCRIPT=${TWS_HOME}/StartUp

if [ -f ${TWS_START_SCRIPT} ]then

case "$1" instart)

echo -n "Starting Tivoli Workload Scheduler instance"${TWS_START_SCRIPT}exit $?

;;*)

echo "Usage: $0 {start}"exit 1;;

esacelse

exit 5fi

Application server tasksThe following application server tasks might need to be performed:

Application server - starting and stoppingUse the startappserver and stopappserver commands or the equivalent from theDynamic Workload Console to start or stop the embedded WebSphere ApplicationServer. (see Tivoli Workload Scheduler: User's Guide and Reference for a description ofthese commands.)

These commands also stop appservman, the service that monitors and optionallyrestarts the application server.

If you do not want to stop appservman, you can issue startWas or stopWas,supplying the –direct argument.

The full syntax of startWas and stopWas is as follows:

UNIX

Start the application serverstartWas.sh [-direct]

Stop the application serverstopWas.sh [-direct]

-user <user_ID>-password <password>

Note: The above syntax for stopping the embedded WebSphereApplication Server is applicable only if all components areintegrated with your Tivoli Workload Scheduler environment. Ifyour Dynamic Workload Console or z/OS Connector are not


||||||||||||||||||||||||||

|

integrated (they do not share the same WebSphere ApplicationServer with your Tivoli Workload Scheduler installation), you mustuse the following syntax:stopWas.sh -direct

-user <user_ID>-password <password>

where the -direct argument is mandatory.

Windows

Start the application serverstartWas.bat [-direct]

[-service <service_name>][-options <parameters>]

Stop the application serverstopWas.bat [-direct]

[-service <service_name>][-wasHome <installation_directory>][-options <parameters>]

where the arguments are as follows:

–directOptionally starts or stops the application server without starting orstopping the application server monitor appservman.

For example, you might use this after changing some configurationparameters. By stopping WebSphere Application Server without stoppingappservman, the latter will immediately restart WebSphere ApplicationServer, using the new configuration properties. This argument ismandatory on UNIX when the product components are not integrated.

–options <parameters>Optionally supplies parameters to the WebSphere Application ServerstartServer or stopServer commands. See the WebSphere ApplicationServer documentation for details.

–password <password>Defines the password to be used when stopping the application server onUNIX.

–service <service_name>Defines the WebSphere Application Server service name, if it is not thedefault value of IBM WebSphere Application Server V6 - <TWS_user>

–user <user_ID>Defines the user ID to be used when stopping the application server onUNIX.

–wasHome <installation_directory>Defines the WebSphere Application Server installation directory, if it is notthe default value.

Application server - automatic restart after failureIf you experience any problems with the application server failing, a service isavailable that not only monitors its status, but can also restart it automatically inthe event of failure. The service is called appservman, and it is enabled andcontrolled by the local options on the computer where the application server isrunning.


The following sections describe the service, how it works, and how it is controlled:v “Appservman - how it works”v “Controlling appservman”v “Starting and stopping the application server and appservman” on page 303v “Monitoring the application server status” on page 304v “Obtaining information about application server failures” on page 305v “Events created by appservman” on page 305

Appservman - how it worksAppservman is a service that starts, stops and monitors the application server. It alsooptionally restarts the application server in the event that the latter fails.Appservman can be controlled not just from nodes running the application server,but also from any other node running conman.

It is launched as a service by netman when starting Tivoli Workload Scheduler, andit itself then launches the application server. Netman also launches it when theconman startappserver command is run.

Appservman is stopped when Tivoli Workload Scheduler is shutdown. In addition,Netman stops both the application server and appservman when you use the conmanstopappserver command, or, on Windows only, when you issue the Shutdown–appsrv command.

While it is running appservman monitors the availability of the application server,sending events that report the status of the application server. If the automaticrestart facility is enabled, and the application server fails, the service determinesfrom the restart policy indicated in the localopts options if it is to restart theapplication server. If the policy permits, it will restart the application server, andsend events to report its actions.

The WebSphere Application Server utilities startWas and stopWas by default startand stop the application server and appservman using the startappserver andstopappserver commands. However, these utilities can be instructed to start andstop the application server without stopping appservman by using the startWas andstopWas utilities with the –direct option.

Controlling appservmanAppservman is controlled by the following local options (in the localopts file):

Appserver auto restartDetermines if the automatic restart facility is enabled.

The default is yes. To disable the option set it to no.

Appserver check intervalDetermines how frequently the service checks on the status of theapplication server. You should not set this value to less than the typicaltime it takes to start the application server on the computer.

The default is every 5 minutes.

Appserver min restart timeDetermines the minimum time that must elapse between failures of theapplication server for the automatic restart to work. This option stopsappservman from immediately restarting the application server if it fails oninitial startup or when being restarted.

The default is 10 minutes.


Appserver max restartsDetermines the maximum number of times that appservman willautomatically restart the application server within a time frame determinedby you (Appserver count reset interval).

The default is 5 restarts.

Appserver count reset intervalDetermines the time frame for the maximum number of restarts(Appserver max restarts).

The default is 24 hours.

Appserver service nameThis is used in Windows only. It is generated as follows:IBMWAS61Service - <TWS_user>

How to use the options: The default settings are a good starting point. Follow theindications below if you are not satisfied that the settings are maintaining thecorrect availability of the application server:v If the application server is not restarting after failure, check the following:

– That the Appserver auto restart is set to yes.– That the Appserver check interval is not set to too high a value. For example, if

this value is set to 50 minutes, instead of the default 5, an early failure of theapplication server might wait 45 minutes before being restarted.

– That Appserver min restart time is sufficient for the application server to fullyrestart. If, when the server checks the status of the application server, it findsthat the application server is still starting up, in some circumstances it is notable to distinguish the starting-up state from the failed state, will report it asfailed, and try and restart it again. With the same result. This will continueuntil Appserver max restarts is exceeded. If this is the case, make Appserver minrestart time larger.

v If the application server is failing infrequently, but after several failures is notrestarting, set the Appserver max restarts option to a higher value or the Appservercount reset interval to a lower value, or both. In this case it might beadvantageous to study the pattern of failures and tailor these options to giveyou the required availability

Starting and stopping the application server and appservmanIf you need to stop and restart the application server, for example to implement achange in the application server configuration, use the following commands:

stopappserver[domain!]workstation [;wait]This command stops the application server and appservman. You canoptionally stop the application server on a remote workstation. Theoptional ;wait parameter tells conman to suspend processing until thecommand reports that both the application server and the service havestopped.

startappserver[domain!]workstation [;wait]This command starts the application server and appservman. You canoptionally start the application server on a remote workstation. Theoptional ;wait parameter tells conman to suspend processing until thecommand reports that both the application server and the service are upand running.

To stop and start the application server without stopping appservman, see“Application server - starting and stopping” on page 300.


Configuring user and password for running conmanstopappserverWhen you run conman stopappserver, the appserverman process first checks ifWebSphere Application Server can retrieve the user's credentials (username andpassword) from the soap.client.props file located in the WebSphere ApplicationServer profile. If the check is negative, appserverman reads them from the useroptsfile of the user and runs the stopServer.sh (bat) script to pass them toWebSphere Application Server.

To be able to run conman stopappserver, you must therefore complete one of thefollowing two customization procedures to provide the user credentials toWebSphere Application Server:v Customize the user name (com.ibm.SOAP.loginUserid) and password

(com.ibm.SOAP.loginPassword) properties in the soap.client.props file locatedin:

TWS_home/appserver/profiles/twsprofile/properties/ (Version 8.4 and earlier master)TWS_home/appserver/profiles/twsconnprofile/properties/ (Version 8.4 and earlier agents)TWA_home/eWAS/profiles/TIPProfile/properties/ (Version 8.5 and later master and agents)

You must also:1. Set property com.ibm.SOAP.securityEnabled to true in the same file to enable

the SOAP client security2. Run the encryptProfileProperties.sh script to encrypt the password. See

the Tivoli Workload Scheduler Administration Guide for more information onthis application server tool.

v Customize the Attributes for conman (CLI in version 8.4) connectionssection in the localopts file by specifying the details of the connector or of themaster domain manager.You must also:1. Create (or customize if already present) the useropts file manually, adding

the USERNAME and PASSWORD attributes for the user who will runstopappserver. Make sure the useropts file name is entered in the USEROPTSkey in the Attributes for conman (CLI) connections section. See theAdministration Guide for further details.

2. Encrypt the password in the useropts file simply by running conman.

Monitoring the application server statusTo see the current status of the application server at any time view the STATE fieldin the workstation details.

This field contains a string of characters that provide information about thestatuses of objects and processes on the workstation. The state of the applicationserver is a one-character flag in this string, which has one of the following valuesif the application server is installed:[A|R]

where:

A The WebSphere Application Server is running.

R The WebSphere Application Server is restarting.

If the application server is down or if it was not installed, neither value of the flagis present in the STATE entry.


Obtaining information about application server failuresAppservman does not provide information about why the application server hasfailed. To obtain this information, look in the application server log files (see theTivoli Workload Scheduler: Troubleshooting Guide).

Events created by appservmanAppservman sends an event called ApplicationServerStatusChanged from theTWSObjectsMonitor provider to the configured event monitoring process every timethe status of the application server changes.

Application server - encrypting the profile properties filesYou use the encryptProfileProperties script to encrypt passwords in thefollowing embedded WebSphere Application Server property files:v TWA_home/eWAS/profiles/TIPProfile/properties/soap.client.props

v TWA_home/eWAS/profiles/TIPProfile/properties/sas.client.props

v TWA_home/eWAS/profiles/TIPProfile/properties/sas.stdclient.properties

v TWA_home/eWAS/profiles/TIPProfile/properties/sas.tools.properties

where PROFILE can be one of the following:

Component PROFILE

Master domain manager twsprofile

Distributed connector twsconnprofile

z/OS connector twszconnprofile

An example of when you might use the encryption function is when creating SSLkey-stores. You would type the passwords in the key-stores and then encrypt themusing the encryptProfileProperties script. See Tivoli Workload Scheduler: Planningand Installation Guide.

The script uses PropFilePasswordEncoder.bat. Restart the server for the changes totake effect.

Encrypt properties uses the following syntax:encryptProfileProperties.bat (.sh)

Application server - updating the Windows services aftermodifications

If you have modified any of the following, you must update the Windows servicethat runs the application server:v The user ID and password of the local operating system user that runs the

application server processv The installation directory of the embedded WebSphere Application Serverv The directory where the Tivoli Workload Scheduler application server profile is

stored

To update the service, run the updateWasService command from the<TWA_home>/wastools directory.

Note: You can also use this command to change the way that the applicationserver is started.


At runtime, the script calls WASService.exe.

updateWasServiceFormat

updateWasService –userid <TWS_user> –password <TWS_user_password>[–wasuser <WAS_user> –waspassword <WAS_user_password>][–startType {automatic | manual | disabled}][–wasHome <WebSphere_install_directory>][–profilePath <server_profile_directory>]

Parameters

–userid <TWS_user> –password <TWS_user_password>Supply the <TWS_user> and its password.

[–wasuser <WAS_user> –waspassword <WAS_user_password>]The user that the local operating system uses to run the application processis set by default to the <TWS_user>. If you want to change it to a differentuser and password, supply this parameter.

Note: Due to a known problem with this utility, when you change thepassword you must first use the Windows facility for changing thepassword, as described in “Action 7 - Windows - update Windowsservices” on page 281, and then run this utility, giving the newpassword you have just set as the <WAS_user_password>.

[–startType {automatic | manual | disabled}]The application server starts automatically by default, when the computeris started. If you want to have a different behavior supply this parameter.

[–wasHome <WebSphere_install_directory>]If you have changed the name of the installation directory of theembedded WebSphere Application Server, supply this parameter indicatingthe new name.

[–profilePath <server_profile_directory>]If you have changed the name of the directory where the Tivoli WorkloadScheduler application server profile is stored, supply this parameterindicating the new name.

Application server - updating the SOAP properties afterchanging the WebSphere Application Server user or itspassword

If you have changed the user ID or the password of the WebSphere ApplicationServer administration user either for Tivoli Workload Scheduler or the DynamicWorkload Console, you must also update the SOAP client properties.

To update the properties, run the updateWas.sh/.bat command from the<TWA_home>/wastools directory.

After using this command you must restart the application server.

updateWas.shFormat

updateWas.sh –user <new_WAS_admin_user> –password <password>


Parameters

–user <new_WAS_admin_user> –password <password>Supply the user and password of the new WebSphere Application Serveradministration user that you want to be configured as the credentials inthe SOAP client properties.

Application server - configuration files backup and restoreThe application server has configuration files, which should be backed upwhenever you change them. Use the backupConfig script in the<TWA_home>/wastools directory.

The files are restored, if necessary, using the restoreConfig script in the samedirectory.

There is no need to stop the application server to perform the backup, but youmust stop and restart the server if you have restored the files from a previousbackup.

For further information, see the IBM Redbooks: WebSphere Application Server V6System Management & Configuration Handbook.

Backup usageBackup uses the following syntax:backupConfig.bat [backup_file]

[-nostop][-quiet][-logfile file_name][-replacelog][-trace][-username user_ID][-password password][-profileName profile][-help]

The following is an example of backupconfig.bat:C:\Program Files\ibm\TWA0\wastools>backupConfig.batADMU0116I: Tool information is being logged in file

C:\Program Files\ibm\TWA0\eWAS\profiles\TIPProfile\logs\backupConfig.log

ADMU0128I: Starting tool with the twsprofile profileADMU5001I: Backing up config directory

C:\Program Files\ibm\TWA0\eWAS\profiles\TIPProfile\config to fileC:\Program Files\ibm\TWA0\wastools\WebSphereConfig_2005-12-12.zip

ADMU0505I: Servers found in configuration:ADMU0506I: Server name: server1ADMU2010I: Stopping all server processes for node DefaultNodeADMU0512I: Server server1 cannot be reached. It appears to be stopped........................................................................ADMU5002I: 137 files successfully backed up

Restore usageRestore uses the following syntax:restoreConfig.bat backup_file

[-location restore_location][-quiet][-nowait][-logfile file_name][-replacelog][-trace]


[-username user_ID][-password password][-profileName profile][-help]

The following is an example of restoreConfig.bat:C:\Program Files\ibm\TWA0\wastools>restoreConfig.bat WebSphereConfig_2005-12-11.zipADMU0116I: Tool information is being logged in file

C:\Program Files\ibm\TWA0\eWAS\profiles\TIPProfile\logs\restoreConfig.log

ADMU0128I: Starting tool with the twsprofile profileADMU0505I: Servers found in configuration:ADMU0506I: Server name: server1ADMU2010I: Stopping all server processes for node DefaultNodeADMU0512I: Server server1 cannot be reached. It appears to be stopped.ADMU5502I: The directory C:\Program Files\ibm\TWA0\eWAS\profiles\TIPProfile\config

already exists; renaming toC:\Program Files\ibm\TWA0\eWAS\profiles\TIPProfile\config.old

ADMU5504I: Restore location successfully renamedADMU5505I: Restoring file WebSphereConfig_2005-12-11.zip to location

C:\Program Files\ibm\TWA0\eWAS\profiles\TIPProfile\config.....................................................................ADMU5506I: 127 files successfully restoredADMU6001I: Begin App Preparation -ADMU6009I: Processing complete.

Application server - changing the host name or TCP/IP portsTo modify the host name of the computer where the application server is installed,or the TCP/IP ports it uses, run the changeHostProperties script.

The procedure requires you to stop the application server, create a text file of thecurrent host properties, edit the file, run the utility and restart the applicationserver. Find information about how to do this as follows:v “Application server - using the utilities that change the properties” on page 312


v “Changing host properties” on page 309 lists all the host properties and givesother reference information about the utility

v When editing the text file of the current host properties, do as follows:1. Edit the text file and locate the following properties:

################################################################# Host Configuration Panel################################################################

# Old HostnameoldHostname=myoldhost.mydomain.com

# New HostnamenewHostname=myhost.mydomain.com

################################################################Ports Configuration Panel################################################################bootPort=41117bootHost=myhost.mydomain.comsoapPort=41118soapHost=myhost.mydomain.comhttpPort=41115httpHost=*httpsPort=41116httpsHost=*


adminPort=41123adminHost=*adminSecurePort=41124adminSecureHost=*sasPort=41119sasHost=myhost.mydomain.comcsiServerAuthPort=41120csiServerAuthHost=myhost.mydomain.comcsiMuthualAuthPort=41121csiMuthualAuthHost=myhost.mydomain.comorbPort=41122orbHost=myhost.mydomain.com

The rules for changing these values are as follows:– To change the host name, supply both oldHostname and newHostname. Also

check that the values of bootHost and csiServerAuthHost are set correctly(normally to the new host name).

– If you change the host name, the old host port settings are used, unlessyou specifically change them.

– If you do not supply a port number it is not changed.Do not change any other properties.

Note: The utility might display a message from the application server(WASX7357I:). You can ignore this message.

Changing host propertiesYou use the changeHostProperties script to change the workstation host name inthe WebSphere Application Server configuration files, or the TCP/IP ports used byWebSphere Application Server. To change or disable TCP/IP Ports see “DisablingTCP/IP ports” on page 310.

The procedure for running the script is described in detail in “Application server -using the utilities that change the properties” on page 312, but in summary you dothe following:v Run showHostProperties.sh (.bat) > my_file_name to obtain the current

propertiesv Edit my_file_namev Run changeHostProperties.sh (.bat) my_file_name

Note: my_file_name must be the fully qualified path of the file.

The change utility calls the wsadmin utility by runningChangeHostProperties.jacl with the properties file as input.

Only the WebSphere Application Server serverindex.xml configuration file isaffected by this script. The path of the file is:TWA_home/eWAS/profiles/TIPProfile/config/cells/DefaultNode/nodes/DefaultNode/serverindex.xml

where <profile> is one of twsprofile, twsconnprofile, or twszconnprofile for themaster domain manager, the distributed connector and the z/OS connectorrespectively.

The following is a list of the properties that can be changed with this utility:


################################################################# Host Configuration Panel################################################################

# Old HostnameoldHostname=myoldhost.romelab.ibm.it.com

# New HostnamenewHostname=mynewhost.romelab.ibm.it.com

################################################################Ports Configuration Panel################################################################bootPort=41117bootHost=myhost.mydomain.comsoapPort=41118soapHost=myhost.mydomain.comhttpPort=41115httpHost=*httpsPort=41116httpsHost=*adminPort=41123adminHost=*adminSecurePort=41124adminSecureHost=*sasPort=41119sasHost=myhost.mydomain.comcsiServerAuthPort=41120csiServerAuthHost=myhost.mydomain.comcsiMuthualAuthPort=41121csiMuthualAuthHost=myhost.mydomain.comorbPort=41122orbHost=myhost.mydomain.com

All of the properties in the properties file are optional. When you are modifyingthe properties file you should be aware of the following:v When oldHostname and newHostname are provided (these settings must be

provided together), the host property related to each port is updated when it hasnot been provided in the properties file and the current value matchesoldHostname

v Port settings are updated only if they are provided in the properties filev A port-specific host setting, such as httpHost is not updated if not specified

except when its current setting matches oldHostname

v An empty setting is considered as not provided

Disabling TCP/IP ports: Using the changeHostProperties script you can alsodisable some TCP/IP ports by setting the value of the following correspondingproperties to false. If you are using Secure Sockets Layer Communication (SSL) inyour network, disabling the non-secure HTTP and Administrative Console portswill ensure that only encrypted communication occurs in your network. By defaultthese ports are all enabled. To disable them use the following properties:

httpEnabledTo disable the httpPort.

httpsEnabledTo disable the httpsPort.

adminEnabledTo disable the adminPort.


adminSecureEnabledTo disable the adminSecurePort.

Displaying the current host properties: To display the current properties, use thefollowing utility:

UNIX showHostProperties.sh

WindowsshowHostProperties.bat

Application server - changing the trace propertiesYou can use the changeTraceProperties script to change the embedded WebSphereApplication Server trace properties.

The script calls the wsadmin utility by running the ChangeServerTracing.jacl witha properties file whose template is TracingProps.properties.

See the Tivoli Workload Scheduler: Troubleshooting Guide for full details on how tochange the trace settings.

The properties file defines the following trace modes:wsmm_odr=com.ibm.ws.xd.comm.*=all:com.ibm.wsmm.grm.Controller=all:com.ibm.ws.xd.work*=all:com.ibm.ws.xd.arfm.*=all:com.ibm.wsmm.policing.*=all:com.ibm.wsmm.xdglue.*=all:com.ibm.ws.odc.ODCTreeImpl$Save=allwsmm_node=com.ibm.ws.xd.comm.*=all:com.ibm.ws.xd.placement*=all:com.ibm.ws.xd.arfm.*=allreset=*=infowsmm007=com.ibm.wsmm.policing.*=alldcs=DCS=finest:RMM=finestham=hamanageditem=alltcpdcs=DCS=finest:RMM=finest:com.ibm.ws.tcp.channel.*=finesttcp=com.ibm.ws.tcp.channel.*=finestvizcache=com.ibm.ws.xd.visualizationengine.cacheservice.cacheimpl.*=allruntime=com.ibm.ws.console.xdruntime.*=allproxy=com.ibm.ws.console.proxy.*=allplacement=com.ibm.ws.xd.placement*=all=enabledcharting=com.ibm.ws.console.chart.*=alldwlm=com.ibm.ws.dwlm.*=alloperationalpolicy=com.ibm.ws.xd.operationalpolicymonitor.*=allwsmm_na=*=info:com.ibm.ws.xd.comm.*=all:com.ibm.ws.xd.placement*=all:com.ibm.ws.xd.workprofiler.*=all:com.ibm.ws.xd.arfm.*=all:com.ibm.ws.dwlm.*=all:com.ibm.ws.xd.hmm.*=all:com.ibm.ws.xd.admin.utils.*=all:com.ibm.ws.clustersensor.impl.*=all:com.ibm.ws.xd.placement.memory.profiler.impl.*=offwsmm_o=*=info:com.ibm.ws.xd.comm.*=all:com.ibm.wsmm.grm.Controller=all:com.ibm.ws.xd.workprofiler.*=all:com.ibm.ws.xd.arfm.*=all:com.ibm.wsmm.policing.*=all:com.ibm.wsmm.xdglue.*=all:com.ibm.ws.dwlm.*=all:com.ibm.ws.dwlm.client.*=offdmgr=com.ibm.ws.odc.*=all:com.ibm.ws.xd.visualizationengine.cacheservice.cacheimpl.DeploymentTargetCache*=allgrid=grid.capacityplacement=allwebcontainer=com.ibm.ws.webcontainer.*=all:com.ibm.ws.http.*=allodc=com.ibm.ws.odc.*=all:com.ibm.ws.dwlm.client.*=all:com.ibm.ws.xd.dwlm.client.*=all:com.ibm.ws.proxy.*=allwssec_all=com.ibm.ws.security.*=all


wssec_tws_all=com.ibm.ws.security.*=all:com.ibm.tws.*=alltws_all=com.ibm.tws.*=alltws_alldefault=com.ibm.tws.*=error=enabledtws_db=com.ibm.tws.dao.model.*=all:com.ibm.tws.dao.rdbms.*=alltws_planner=com.ibm.tws.planner.*=all:com.tivoli.icalendar.*=all:com.ibm.tws.runcycles.*=all:com.ibm.tws.conn.planner.*=all:com.ibm.tws.cli.planner.*=alltws_cli=com.ibm.tws.cli.*=all:com.ibm.tws.objects.*=alltws_utils=com.ibm.tws.util.*=alltws_conn=com.ibm.tws.conn.*=all:com.ibm.tws.objects.*=all:com.ibm.tws.updatemanager.*=all:com.ibm.tws.dao.plan.*=alltws_secjni=com.ibm.tws.audit.*=all:com.ibm.tws.security.*=allactive_correlation=com.ibm.correlation.*=alltws_jni=TWSJNI=alltws_all_jni=com.ibm.tws.*=all:TWSJNI=alltws_all_act=com.ibm.tws.*=all:com.ibm.correlation.*=alltws_broker_all=com.ibm.scheduling.*=all:TWSAgent=alltws_broker_rest=com.ibm.scheduling.jobmanager.rest.*=alltws_engine_broker_all=com.ibm.tws.*=all:com.ibm.scheduling.*=all:TWSAgent=alltws_bridge=TWSAgent=alltws_db_transactions=com.ibm.tws.planner.currentplan.PlannerEngine=all:com.ibm.tws.dao.rdbms.util.DatabaseTransaction=all

You can define other trace modes and update TracingProps.properties or create anew properties file.

Two settings that must not be changed are the server name (default server1), andthe node (default DefaultNode).

WebSphere Application Server tools - reference

Application server - using the utilities that change the propertiesThis section documents a common procedure that you are advised to follow whenusing the following utilities:v changeDataSourcePropertiesv changeHostPropertiesv changeSecurityProperties

To avoid the risk of changing a configuration value inadvertently, you shouldfollow a procedure that creates a file containing the current properties, edit it tothe values you require, and apply the changes. The details are as follows:1. Log on to the computer where Tivoli Workload Scheduler is installed as the

following user:

UNIX root


2. Access the directory: <TWA_home>/wastools3. Stop the WebSphere Application Server using the conman stopappserver

command (see “Starting and stopping the application server andappservman” on page 303)

4. From that same directory run the following script to create a file containingthe current properties:

UNIX show<property_type>Properties.sh > my_file_name


Windowsshow<property_type>Properties.bat > my_file_name

where <property_type> is one of the following:v DataSourcev Hostv Security

5. Edit my_file_name with a text editor. Check the start of the file. The commandmight have written a message from the application server (WASX7357I:) at thebeginning of the file. Delete this message.

6. Change the value of the configuration parameters, according to yourrequirements. You do not need to supply all of the parameters in the file.

7. Save the file my_file_name.8. Run the script:

Windowschange<property_type>Properties.bat my_file_name

UNIX change<property_type>Properties.sh my_file_name

where <property_type> is the same as used in step 4 on page 312, andmy_file_name is the fully qualified path of the file containing the newparameters.The properties are updated, according to the rules given in the descriptions ofeach property type.


10. Check that the change has been implemented in Tivoli Workload Scheduler.

Understanding the templatesAs indicated in the overview to these utilities, a template file of properties issupplied with the product for each of these utilities. However, this template filedoes not contain any of the configuration values that were created by the productinstallation process or any previous uses of the configuration utilities. If you decideto use the template instead of creating the properties document as described instep 4 on page 312, you must be careful to ensure that the values you enter in thefile for every parameter are those that you require to be used by the applicationserver.

Application server utilitiesThis section provides reference information about the utilities provided with theembedded WebSphere Application Server that supports Tivoli Workload Scheduler.

The utilities are a set of scripts based on Windows batch files, UNIX and Linuxshell scripts, and WebSphere Jacl procedures. The scripts run the WebSphereApplication Server embedded utilities that perform the reconfiguration. Many ofthem load configuration settings from a properties file. Templates for these files arealso provided.

Tivoli Workload Scheduler installs the following Windows scripts:v backupConfig.batv brokerApplicationStatus.batv changeBrokerSecurityProperties.bat


v changeDataSourceProperties.batv changeHostProperties.batv changePassword.batv changeSecurityProperties.batv changeTraceProperties.batv encryptProfileProperties.batv InstallOracledataSource.batv InstallTDWCdataSource.batv manage_ltpa.batv modifyThreadPool.batv restoreConfig.batv setEnv.batv showBrokerSecurityProperties.batv showDataSourceProperties.batv showHostProperties.batv showSecurityProperties.batv startBrokerApplication.batv startWas.batv stopBrokerApplication.batv stopWas.batv updateWas.batv updateWasService.bat

Tivoli Workload Scheduler installs the following UNIX and Linux scripts:v backupConfig.shv brokerApplicationStatus.shv changeBrokerSecurityProperties.batv changeDataSourceProperties.shv changeHostProperties.shv changePassword.shv changeSecurityProperties.shv changeTraceProperties.shv createCustomRegistryforPAM.shv encryptProfileProperties.shv InstallOracledataSource.shv InstallTDWCdataSource.shv manage_ltpa.shv modifyThreadPool.shv restoreConfig.shv setEnv.shv showBrokerSecurityProperties.shv showDataSourceProperties.shv showHostProperties.shv showSecurityProperties.shv startBrokerApplication.sh


v startWas.shv stopBrokerApplication.shv stopWas.shv manage_ltpa.shv modifyThreadPool.shv InstallOracledataSource.shv updateWas.shv wasstart.sh

The following templates are installed for both Windows and UNIX operatingsystems:v BrokerSecurityProps.propertiesv DataSourceProps.propertiesv HostConfigProps.propertiesv SecurityProps_FULL.propertiesv SecurityProps_TEMPLATE.propertiesv TDWCDatasource.propertiesv TracingProps.properties

See “Application server - using the utilities that change the properties” on page312 to understand how the templates should be used.


Chapter 10. Performance

This chapter provides information about issues that impact performance. Use thisinformation both to prevent problems occurring and to help resolve problems thathave occurred.

The topics discussed are as follows:v “Network traffic”v “Tracing”v “Logging” on page 318v “Maintaining the database” on page 318v “Symphony file sizing” on page 318v “Tuning a UNIX domain manager to handle large numbers of fault-tolerant

agents” on page 318v “Tuning job processing on a workstation” on page 318v “Tuning the database” on page 319v “Tuning the embedded WebSphere Application Server” on page 319v “Too many manual job submissions” on page 320v “Too many file dependency checks” on page 320v “Workload spreading” on page 320v “Improving job-processing performance” on page 320v “Mailbox caching - advantages and disadvantages” on page 321v “Setting the synch level parameter” on page 322v “The fault-tolerant switch manager - impact on performance” on page 322v “Scalability” on page 323v “Multiple Dynamic Workload Console production plan reports” on page 328v “Dynamic Workload Console - adjusting session timeout settings” on page 329

Network trafficA full description of how a Tivoli Workload Scheduler network is structured, andhow the different nodes communicate, is provided at the beginning of Chapter 6,“Network administration,” on page 159. In particular, see “Optimizing thenetwork” on page 166, which explains how to design and operate your TivoliWorkload Scheduler network to maximize performance.

TracingThe performance of any workstation can be impacted by the level of tracing it hasto perform. The Tivoli Workload Scheduler: Troubleshooting Guide has a chapter whichexplains the diagnostic tools that are available, and within that chapter there is asection about the Tivoli Workload Scheduler In-flight Tracing utility, which, as wellas discussing how the feature works, also describes how to customize it to enhanceworkstation performance.

The performance might also be impacted by the tracing activities on theWebSphere Application Server.


LoggingThe performance of any workstation can be impacted by the way the TivoliWorkload Scheduler logging mechanism uses memory. The default settings appliedin this version are designed to ensure the maximum performance. However,because these defaults are different from the defaults in earlier versions, if you areexperiencing performance problems, it is advisable to check that these settingshave not been in some way overwritten by the previous values. In the diagnostictools chapter of Tivoli Workload Scheduler: Troubleshooting Guide, there is a sectionabout CCLog, which, apart from discussing how to customize CCLog, alsodescribes how to check the CCLog processing defaults.

Maintaining the databaseMaintaining the database in a good state of organization is important to optimizeperformance. See “Reorganizing the database” on page 219 for details.

Symphony file sizingTo calculate the size of the Symphony file and understand its impact onperformance, see “Avoiding full file systems” on page 220.

Tuning a UNIX domain manager to handle large numbers offault-tolerant agents

The performance of domain managers on UNIX is impacted if they serve largenumbers of fault-tolerant agents. Improvements can be obtained by modifying thekernel parameters. The precise settings differ according to operating system, andyou might need to test different settings to obtain optimum performance.

The following is an example of the kernel settings for HP-UX to handleapproximately 200 fault-tolerant agents:

max_thread_proc=256nprocess=1800maxusers=120maxuprc=1700nflocks=500maxfiles=1024

Tuning job processing on a workstationThis section explains how to tune selected options in the Tivoli WorkloadScheduler localopts file to improve Tivoli Workload Scheduler performance. Theseoptions control the period between successive instances of an activity. Table 61 onpage 319 shows the activities to be tuned, the corresponding option that can be setin the localopts file, and how the changed value impacts performance.


Table 61. Options for tuning job processing on a workstation

Activity Option Impact on performance

batchman periodically scans the Symphony file forjobs ready to be processed.

bm look In all these cases, a shorter time means morefrequent scans, using more cpu resources, andimpacting other processes that are running.However, it also means that for all activitieswaiting time is kept to a minimum. If throughputis important and the workstation has plenty ofmemory, try shortening the times.

A longer period between successive activitiesmeans jobs take longer to run, because there arelonger waits for each activity. However, thereduced frequency of the scans means that morememory is available for jobs because less is beingused by these monitoring activities.

Consider the meaning of the various options. Ifyour objective is to run the jobs as quickly aspossible, but you are not concerned about howquickly the information about completed jobs isdistributed, you could reduce the wait periods forbm look and jm read, but increase the periods forthe others.

Alternatively, to speed up the overall jobprocessing time (from initial job launch to theupdate with the completion status), you can tunebm look, jm look, and mm read.

jobman accesses the Courier.msg file to see ifthere are jobs that need to be launched.

jm read

After having launched a job jobman checksperiodically for job completion status.

jm look

mailman looks periodically in the Mailbox.msg forcompleted jobs.

mm read

batchman checks periodically in Intercom.msg forjobs that are complete so that it can update theSymphony file.

bm read

If you decide to tune these setting do the following:v Test the result in a test system before applying changes in your production

environment. To get worthwhile results, the test environment must have thesame characteristics as the production environment.

v Modify only the parameters that are necessary. It is better to modify one at atime and thoroughly test the change in performance, rather than changing all atonce.

v Make a backup copy of the localopts file to ensure you can revert to the defaultoptions if necessary.

Stop and start the agent to activate changes applied to the localopts file.

Tuning the databaseTo learn about tuning the database, consult the relevant product documentation:

DB2 Go to hhttp://publib.boulder.ibm.com/infocenter/db2luw/v9r5/index.jsp,and select Best practices.

Oracle See the Performance Tuning Guide in the Oracle documentation set.

Tuning the embedded WebSphere Application ServerTo learn about tuning the embedded WebSphere Application Server, consult theappropriate documentation.

Chapter 10. Performance 319


Go to http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp, selectWebSphere Application Server (Distributed platforms and Windows), Version7.0 and then Tuning performance.

Inadequate Java heap sizeThe default Java maximum heap size might be too small for your requirements. Ifyou have any reason to suspect the performance of the embedded WebSphereApplication Server, increase the heap size as described in “Increasing applicationserver heap size” on page 324.

Too many manual job submissionsTivoli Workload Scheduler is designed for maximum efficiency when handling jobssubmitted using a scheduled plan. Consequently, it is less adapted to processingmanually submitted jobs. Thus, performance can be improved by reducing thenumber of manually submitted jobs.

Too many file dependency checksEach file dependency check has an impact on performance. If you design a planthat is constantly checking many file dependencies, you reduce the performance ofthe workstation where these jobs are being run.

If multiple “opens” files are being used as a dependency, use the “–a” (and)option. For example, to check if three home directories /tom, /dick, and /harryexist, before launching myjob issue the following:job2 opens "/users" (-d %p/tom -a -d %p/dick -a -d %p/harry)

This checks for all three directories at the same time, instead of looking for eachdirectory separately.

Other factors that impact performance when evaluating file dependencies are thebm check parameters in the localopts file. These are documented in the TivoliWorkload Scheduler: Planning and Installation Guide in the chapter on customization.

Workload spreadingWhatever jobs you have to schedule, try and spread them out through theproduction period so that there is no concentration in any one moment. Try also toavoid scheduling activities during times when normal user traffic in the network isvery heavy, for example during the morning when users commence working anddeal with accumulated emails.

Failure to do this might cause a bottleneck at the Mailbox.msg queue, which causesdelays in updating the Symphony file, which in turn creates delays in theavailability of job statuses to conman, the Dynamic Workload Console.

Improving job-processing performanceThe processing and monitoring of jobs on a workstation is controlled primarily byvarious parameters in the localopts file and the global options maintained byoptman. These parameters are described in the Tivoli Workload Scheduler: Planningand Installation Guide.


|||

http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp

If you are experiencing problems of performance when processing and monitoringjobs, contact IBM Software Support for advice about how to tune these parametersin your particular environment to improve performance.

Mailbox caching - advantages and disadvantagesMailman uses a parameter in the localopts file to decide whether to cachemailbox messages: mm cache mailbox. This section explains the advantages anddisadvantages of the on and off settings of this parameter.

Setting the mm cache mailbox parameter to noThis means that mailman has to make a separate read action for eachmessage before processing it, and then a separate delete action aftersuccessfully processing the message. The I/O activity in performing theseactivities one message at a time is proportionally high for the amount ofdata being read. This has an impact on performance. On the other hand,the processing is simple, in that each message is read, processed, and thenremoved from the mailbox. Any failure of the system at any point meansthat at most one message is replayed and no data is lost.

Setting the mm cache mailbox parameter to yes (default)This means that mailman reads a block of messages into cache memory,processes all of the messages, and then deletes all of them from themailbox. The advantage in I/O time is clear; reading and deleting asequential set of messages in one action is a much more efficient use ofI/O time, than reading and deleting them one-by-one, meaning improvedperformance.

However, if there is a failure of mailman or the operating system, the cacheis lost. On restarting, mailman rereads the set of messages that werepreviously in cache, some of which might already have been processed.For example, if mailman reads a block of 32 messages into cache and hasprocessed 30 of them when a problem occurs, when mailman is restarted itrereads those 32 records and has to process 30 duplicates before being ableto continue where it stopped.

Most events deal with job state changes, and these events can be repeatedwithout creating any problems, and the critical events mechanism is able todeal with the others. However, there is an impact on performance whilethis recovery processing is going on, and if the in-built mechanisms cannothandle the message duplication, a more serious error might occur,ultimately involving the full or partial loss of the mailbox contents.

The number of messages being read in one action is configurable, using theparameter mm cache size. The default value for this parameter is 32messages, and the maximum is 512. Setting this parameter to a valuehigher than the default increases performance during correct working, butdecreases the performance in the event of a failure, for the reasons statedabove. In addition, the additional cache means that the memory requiredby the Tivoli Workload Scheduler engine also increases. If you have aworkstation with limited memory, or memory-heavy applications running,it might be counterproductive to increase the mailbox cache because theoperating system might have to start paging the cache memory.

In conclusion, the default setting maximizes performance; only if you start losingevents should you set it to no.


Setting the synch level parameterThis section describes the impact of the different settings of the synch levelparameter in the localopts file. The synch level parameter only impacts UNIXenvironments.

The I/O activity performed by the Tivoli Workload Scheduler engine in managingplans, job streams, and jobs, consists in reading from and writing to the Symphonyfile and the event files (Mailbox.msg, Intercom.msg, and Courier.msg). When TivoliWorkload Scheduler writes to these files it has more than a straightforward writeoperation to perform. For example, when it writes to the Mailbox.msg file itperforms the actions described in the following pseudo code:

TWS_write_event_lock {Lock Mailbox to write

}

TWS_write_event_update {Check Available SpaceWrite HeaderWrite RecordUpdate Write PointerUnlock Mailbox

}

Each action requires one or more write accesses to the disk. The way these actionsare performed with the different synch level options is as follows:

synch level = highEach write operation on the event files is immediately physically written todisk. This has a heavy impact on performance caused by the high I/Odependency.

synch level = mediumEach write event is considered as a single operation. For example, whileTWS_write_event_lock contains only one action, TWS_write_event_updatecomprises five actions. With synch level at medium, the five actions in thiswrite event would be completed in one physical disk access, thusdrastically reducing the I/O overhead.

synch level = low (default)The operating system decides how and when to synchronize the data todisk. The impact of this option is more difficult to assess, because the rulesare different for each operating system and file system.

The fault-tolerant switch manager - impact on performanceThis section describes the impact that the enablement of the fault-tolerant switchmanager feature has on the performance of the general architecture and theindividual system. The fault-tolerant switch manager is enabled by setting theenSwfaultTol global option to yes. When it is set, the master domain managerdistributes messages to all fault-tolerant agents with FullStatus set to yes.

Enabling this option impacts the following:v Network trafficv Disk space


Note: The fault-tolerant switch manager facility is only available if all of theworkstations in the domain are at version 8.2, fix pack level 4, or higher.

Network TrafficNetwork traffic is unchanged under normal conditions, but is increased during thereplay phase, according to your choice and only under special conditions.

The replay phase is an essential part of the processing performed by the switchmgrcommand. It occurs when the new domain manager processes its Symphony fileagainst its copies of the messages received, as it attempts to update its copy of theSymphony file.

Under normal conditions, the outbound reliability does not create any additionalnetwork traffic, because the messages are only stored for an eventual replayoperation. The multiple inbound connections do not generate additional trafficbecause the traffic that was previously copied by the domain manager to theFullStatus member is now copied to the FullStatus members directly by thefault-tolerant agents.

During the replay phase, the connection protocol initiated by mailman on thebackup domain manager includes a new phase for the replay of messages not sentby the failed domain manager. The impact of the message replay might beimportant, depending on the number of messages "trapped" in the old domainmanager.

Disk SpaceThere are two places within the network where disk space use increases followingthe activation of the additional fault tolerance.

These places are as follows:v On the single fault-tolerant agent. Here, in addition to the tomaster.msg queue,

new queues are created for the other FullStatus fault-tolerant agents. Thesequeues need not be considered, because the impact on a single agent is small.

v On the FullStatus fault-tolerant agents acting as backup domain managers. Herenew ftbox message files are created. Upward traffic to the upper domainmanager is in ftbox/ftup.msg and downward traffic to the lower domainmanager is in ftbox/ftdown.msg.

ScalabilityIn an environment with large numbers of scheduling objects, the following impactsare felt:v “Impact on JnextPlan”v “Impact on reporting” on page 324v “Impact on event rule deployment” on page 324

The resolution for these problems often includes making the following changes:v “Increasing application server heap size” on page 324v “Increasing maximum DB2 log capacity” on page 325

Impact on JnextPlanThe main impact on performance caused by a large network of workstationsrunning many jobs over a production period of many days, is on JnextPlan. The


key factor is the number of job stream instances that JnextPlan needs to handle.JnextPlan has to process each of these instances, and the time it takes to do so is afactor that can only be reduced by ensuring that the master domain manager andthe database are on the most powerful computers possible, and that thecommunication, whether in local or remote, between the master domain managerand the database is maximized.

However, there are some specific measures that need to be taken as the number ofjobs or job stream instances increases:

Number of jobs in the plan exceeds 40 000In this event you need to increase the Java heap size used by theapplication server. The default is 512 MB, and you should at least doublethe heap size when job numbers exceed this level. Follow the procedure in“Increasing application server heap size.”

You have a large number of job stream instances in the plan

DB2 The default DB2 transaction log files cannot handle more than thetransactions generated by about 180 000 job stream instances. Youneed to change the parameters that control the log file sizes or thenumbers of log files that can be created, or both. Follow theprocedure in “Increasing maximum DB2 log capacity” on page 325.

Oracle The number of transactions that can be managed by the Oracle logfiles depends on the way the Oracle database is configured. See theOracle documentation for more details.

Note: If circumstances change and the number of job stream instanceshandled by JnextPlan falls below about 180 000, consider resettingthe log and application server heap size settings to their defaultvalues, to avoid performance problems.

Impact on reportingWhen a report is being processed, extra memory is required to handle largenumbers of scheduling objects. The critical point is approximately 70 000 objects.This problem can be handled by increasing the Java heap size used by theapplication server. Follow the procedure in “Increasing application server heapsize.”

Impact on event rule deploymentWhen deploying large numbers of event rules, extra memory is required. Thecritical point is approximately 8 000 rules. This problem can be handled byincreasing the Java heap size used by the application server. Follow the procedurein “Increasing application server heap size.”

Increasing application server heap sizeFollow this procedure to increase the Java heap size:1. Log on to the computer where Tivoli Workload Scheduler is installed as the

following user:

UNIX root


2. Access the directory: <TWA_home>/wastools



4. Open the following file:<TWA_home>/eWAS/profiles/TIPProfile/config/cells/DefaultNode/nodes/DefaultNode/servers/server1/server.xml

5. Locate the following line:<jvmEntries xmi:id="..."verboseModeClass="false"verboseModeGarbageCollection="false"verboseModeJNI="false"initialHeapSize="16"maximumHeapSize="512"runHProf="false"hprofArguments=""debugMode="false"debugArgs="..."genericJvmArguments=""/>

6. Edit maximumHeapSize="512" and change it at least 1024. This would double themaximum heap size from 512 MB to 1 GB. Ensure that the RAM usage of thecomputer can manage whatever increased size you choose. Save the file.

7. Start the WebSphere Application Server using the conman startappservercommand (see “Starting and stopping the application server and appservman”on page 303)

Increasing maximum DB2 log capacityThe Tivoli Workload Scheduler DB2 database uses a transaction log the maximumsize of which is fundamentally important for the successful running of JnextPlanon very large databases.

The default log consists of 40 primary log files, which are always present, and 20secondary log files, created on demand. Each file is about 4 MB in size, so themaximum log capacity using all of the "secondary" log files as well as the primaryfiles is (40 + 20) x 4 MB = 240 MB.

The log space used by JnextPlan is dependent on the size of the preproductionplan. Approximately every 1000 job stream instances generate transactions thatoccupy 1 MB of space in the log file. Thus, the log files by default have amaximum theoretical capacity of 240 000 job stream instances. However, inpractice, you should allow for at least 25% more space than this algorithmindicates, so the capacity of the default log files is around 180 000 job streaminstances.

If JnextPlan has neared or exceeded that level, you must make more log spaceavailable to DB2.

In addition to performing the above calculation, you can also determine the logspace actually used by a specific instance of JnextPlan and base your log sizerequirement on that figure.

Determining actual DB2 log file usageThe following is the procedure to verify how much space was used by a successfulinstance of the JnextPlan command:1. After JnextPlan has run, log on to the computer where the Tivoli Workload

Scheduler DB2 server is installed, as the DB2 instance owner (UNIX) or DB2Administrator (Windows).


2. Open a DB2 command line window or shell, as follows:





3. Run the following command:db2 "get snapshot for database on TWS" > snapdb.txt

where "TWS" must be changed to the actual database name if different4. Open the snapdb.txt file and look for a section like this:

Log space available to the database (Bytes)= 244315359Log space used by the database (Bytes) = 484641Maximum secondary log space used (Bytes) = 0Maximum total log space used (Bytes) = 581636Secondary logs allocated currently = 0

The value shown in "Maximum total log space used" is the actual space usedfor the DB2 logs. This space should be allocated to DB2 using primary log filesonly: therefore, you should change the number of primary log files and theirsize as necessary to meet this requirement as a minimum.In addition, you are recommended to allocate a secondary log space to DB2. Agood choice for the secondary log files is half the number allocated for theprimary files.

The snapshot command described in step 3 can be run at any time to keep track ofthe current usage of the DB2 log space, without a noticeable impact onperformance. All metrics shown are useful to monitor the current allocation of DB2primary and secondary logs at any time, and to determine any required changes.

Procedure for changing the maximum DB2 log capacityDo this as follows:1. Log on to the computer where the Tivoli Workload Scheduler DB2 server is

installed, as the DB2 instance owner (UNIX) or DB2 Administrator (Windows).2. Open a DB2 command line window or shell, as follows:





3. Run the following commands:db2 update db cfg for <database_name> using LOGFILSIZ <log_file_size>db2 update db cfg for <database_name> using LOGPRIMARY <primary_log_files>db2 update db cfg for <database_name> using LOGSECOND <secondary_log_files>

where:


<database_name>The name of the database:v If you are running this from the computer where the DB2 server is


v You are not recommended to run this procedure from the computerwhere the DB2 client is installed, but if you do so, the installeddefault name is TWS_DB. Supply this value unless you have changedit.

<log_file_size>The log file size in 4 KB pages. The default is 1000 (hence the defaultlog file size of 4MB). Look in the DB2 documentation for details of theimplications of choosing a larger or a smaller log file size. Themaximum value is 262 144 (making the maximum log file size about 1GB).

<primary_log_files>The number of primary log files. The default is 40. The total maximumnumber of log files that DB2 can handle (primary and secondary) is256. Thus, there is a maximum limit of 256 GB for the log, orapproximately 256 million job stream instances! (maximum 256 files x 1GB maximum file size)

<secondary_log_files>The number of secondary log files. The default is 20. If there is enoughfree space on the file system, these additional log files are dynamicallyallocated by DB2 as needed (with a small impact on the performance ofJnextPlan). Because these are only created if required, it is preferable toincrease the number of secondary files, rather than the primary files.Typically, you allocate 50% of the primary log file value.

In making the calculation to allocate the log files, allow at least 25% more spacethan you think you require, to avoid that any slight miscalculation causesJnextPlan to fail.Example: if you have determined from the procedure described in“Determining actual DB2 log file usage” on page 325 that JnextPlan has acurrent use of 320 MB, you could calculate as follows:a. Increase 320 MB by 25%, giving 400 MBb. Determine if you want more log files, or bigger log files, or both, by

reference to the DB2 documentation. For example, you could choose toallocate 40 files with a size of 10 MB, 80 files with a size of 5 MB, or 100files with a size of 4 MB. For the sake of this example, assume you havechosen 80 files with a size of 5 MB, so your LOGPRIMARY value will be 80.

c. Determine the log file size in 4 KB pages to give a log file size of 5 MB -your LOGFILSIZ value will thus be 1250.

d. Determine how many secondary log files are required. If you follow the50% guideline you will need a LOGSECOND value of 40.

4. Log on to the computer where Tivoli Workload Scheduler is installed as thefollowing user:

UNIX root


5. Access the directory: <TWA_home>/wastools



7. On the computer where the DB2 server is installed, stop and start DB2, asfollows:a. Ensure that no other applications are using this instance of DB2, or if they

are that they can be stopped.b. Issue the following command:

db2stop

c. Issue the following command:db2start

Note: It is strongly recommended that you stop and start DB2. If this is aproblem for you, you must at least disconnect all applications from theDB2 instance and reconnect them. DB2 will apply the new parameterswhen you reconnect. If necessary, use the following command to forcethe disconnection of all open connections:db2 "force application all"

8. Start the WebSphere Application Server using the conman startappservercommand (see “Starting and stopping the application server and appservman”on page 303)

Multiple Dynamic Workload Console production plan reportsFrom the Dynamic Workload Console you can launch production plan reports.These are heavy users of CPU time, and if they are requested for the entire plan,they can also take some considerable time to produce. If several are running atonce, they can have a noticeable impact on the performance of the master domainmanager.

If you notice a degradation of performance, you can determine if there are anyreports running by checking for the report work files, as follows;1. Navigate to the operating system's temporary directory2. Look for files that have the following file name template:

TWS-<sequential_number>-extr

Each report currently in progress has one of these work files open. The files areremoved when the report is completed.

3. Check the dates of these files, and consider only recent files (if a report failsduring production at any time, its file remains in the temporary directory untilthe next reboot of the master domain manager or you run an operating systemcleanup process that discards all files in the temporary directory).

There is no direct action to take, as you must wait until the report completes forthe performance to recover.

However, if you note that large numbers of reports are being issued, it mightindicate the following scenario:1. A user issues a report request, expecting it to be available immediately2. When the report does not appear immediately, the user things it has hung,

closes and reopens the browser, and reissues the report. The closing of thebrowser does not stop the report production.


3. The user might repeat this action several times.

In this case, you can take action to remind the user that the production of largereports can be time-consuming, and that it always better to wait.

Dynamic Workload Console - adjusting session timeout settings

The value assigned to the session timeout settings defines after how many minutesa user is automatically logged out from the WebSphere Application Server. If youplan to perform long running operations, or to have many users connectedconcurrently to the Dynamic Workload Console, or expect to have lowperformance on the system where the Dynamic Workload Console is installed, youmight want to increase these values.

Perform these steps to change the values assigned to the timeout settings:1. Open the configuration file:

<TWA_home>\eWAS\profiles\tdwc_profile\config\cells\tdwc_cell\nodes\tdwc_node\servers\tdwc_server\server.xml

2. In the file, search for invalidationTimeout in the following tag:<tuningParams xmi:id="TuningParams_1188622510500"

usingMultiRowSchema="false"maxInMemorySessionCount="1000"allowOverflow="true"scheduleInvalidation="false"writeFrequency="TIME_BASED_WRITE"writeInterval="10"writeContents="ONLY_UPDATED_ATTRIBUTES"invalidationTimeout="30">

This is the parameter that sets the HTTP session timeout. By defaultinvalidationTimeout is set to 30, which means that a user is logged outautomatically after 30 minutes of inactivity.

3. Set invalidationTimeout to an appropriate value for your environment andfor the activities you plan to perform.

4. Save the file.5. Open the configuration file:

<TWA_home>\eWAS\profiles\tdwc_profile\config\cells\tdwc_cell\applications\isclite.ear\

deployments\isclite\deployment.xml

6. In the file, search for invalidationTimeout in the following tag:<tuningParams xmi:id="TuningParams_1188878529796"

usingMultiRowSchema="false"maxInMemorySessionCount="1000"allowOverflow="true"scheduleInvalidation="false"writeFrequency="TIME_BASED_WRITE"writeInterval="10"writeContents="ONLY_UPDATED_ATTRIBUTES"invalidationTimeout="30">

By default, invalidationTimeout is set to 30, which means that a user islogged out automatically after 30 minutes of inactivity.

7. Set invalidationTimeout to an appropriate value for your environment andfor the activities you plan to perform.

8. Save the file.9. Open the configuration file:


<TWA_home>\eWAS\profiles\tdwc_profile\config\cells\tdwc_cell\security.xml

10. In the file, search for timeout in the following tag:<authMechanisms xmi:type="security:LTPA"

xmi:id="LTPA_1" OID="oid:1.3.18.0.2.30.2"authContextImplClass="com.ibm.ISecurityLocalObjectTokenBaseImpl

.WSSecurityContextLTPAImpl"authConfig="system.LTPA"simpleAuthConfig="system.LTPA"authValidationConfig="system.LTPA"timeout="120"keySetGroup="KeySetGroup_lab237165Node01_1">

By default timeout is set to 120, which means that a user is logged outautomatically after 120 minutes regardless of whether the user performed anyactions on the WebSphere Application Server.

11. Set the timeout value in the following section of the file to an appropriatevalue for your environment and for the activities you plan to perform.

12. Save the file.13. Restart the WebSphere Application Server.


Chapter 11. Availability

This chapter describes factors that might affect the availability of Tivoli WorkloadScheduler on a workstation. It covers the following topics:v “Resolving Windows user ID account”v “Using a temporary directory on UNIX”

Resolving Windows user ID account

Tivoli Workload Scheduler needs to resolve the user ID account on Windowsoperating systems to verify the security information.

Windows users can be classified as domain users or local users. Domain users aredefined in the domain controller, while local users are defined in the workstationsof the network.

For a domain user, Tivoli Workload Scheduler requests the primary domaincontroller (or any domain controller for Windows 2000 or 2003 Active Directory),to identify an available domain controller. It then uses this domain controlleridentity to fill out the structure for the user.

For a local user, Tivoli Workload Scheduler makes a request to the localworkstation. Generally, Tivoli Workload Scheduler specifies two cases: one for theTivoli Workload Scheduler user and one for the streamlogon user.

The following is a list of steps that Tivoli Workload Scheduler performs toauthenticate Windows users, and the APIs involved:1. Tivoli Workload Scheduler looks up the user in the reference domain. For the

domain user, the reference domain is the name of the Windows network. Forthe local user, it is the name of the local workstation.API: LookupAccountName.

2. If the user is a domain user, Tivoli Workload Scheduler asks the primarydomain controller for any domain controller that is available to resolve theaccount for the user in the reference domain.API: NetGetAnyDCName for Windows or DsGetDcName for Windows 2000 or 2003.

3. Tivoli Workload Scheduler requests the domain controller (or the localworkstation if the user is local) for information about the user.API: NetUserGetInfo.

Note: On Windows 2000 and 2003, the permissions for this API are containedin the BUILTIN\"Pre-Windows 2000 compatible access" group.

Using a temporary directory on UNIXWhen performing Tivoli Workload Scheduler operations on UNIX, temporary filesare written to the temporary directory on the local workstation. Ensure that the<TWS_user> running operations has read and write access to this directory.


Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this publicationin other countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this publication. The furnishing of this publication does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.1623-14, Shimotsuruma, Yamato-shiKanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases payment of a fee.

The licensed program described in this publication and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corporation in the United States, other countries,or both. If these and other IBM trademarked terms are marked on their firstoccurrence in this information with a trademark symbol (® or ™), these symbolsindicate U.S. registered or common law trademarks owned by IBM at the time thisinformation was published. Such trademarks may also be registered or commonlaw trademarks in other countries. A current list of IBM trademarks is available onthe Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.

Intel is a trademark of Intel Corporation in the United States, other countries, orboth.


http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/legal/copytrade.shtml

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft and Windows are registered trademarks of Microsoft Corporation in theUnited States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof others.

Notices 335

Index

Special characters.jobmanrc 177.rhost, file 177$MASTER variable, resolve in mailman, local option 32

Numerics2001, service in NetConf file 1752002, service in NetConf file 1752003, service in NetConf file 1752004, service in NetConf file 1752005, service in NetConf file 1752006, service in NetConf file 1752007, service in NetConf file 1752008, service in NetConf file 1752009, service in NetConf file 1752010, service in NetConf file 1752011, service in NetConf file 1752012, service in NetConf file 1752013, service in NetConf file 1752014, service in NetConf file 1752015, service in NetConf file 1752016, service in NetConf file 1752017, service in NetConf file 1752018, service in NetConf file 1752021, service in NetConf file 1752022, service in NetConf file 1752023, service in NetConf file 1752501, service in NetConf file 1752502, service in NetConf file 1752503, service in NetConf file 175

Aaccess method, UNIX

local 177remote 177

access to broker serverrestricting 197

access, remote, for command-line, configuring 70accessibility xiiaction, object type, defining access 122Active Directory, configuring LDAP for 155administrative tasks 267

DB2 225Oracle 231

agent 270agent process

monitoring 165agents

critical, positioning 166ah, global option 13al, global option 13altpass, command 274application server

administrative tasks 267automatic restart 301backup master domain manager setting, local option 31changing user password 274configuration backup and restore 307

application server (continued)configuration files: backup and restore 307configuration utilities: background 313encrypting profile properties 305host name, modify 308increase heap size 324master domain manager setting, local option 31monitor 301multiple instances on same system 88security settings, modify 296starting and stopping 300TCP/IP ports, modify 308tuning 319updating the SOAP properties after changing user or

password 306updating the Windows service 305using utilities to change properties 312utilities 313

ApplicationServerStatusChanged event 305approachingLateOffset, global option 13appserver

auto restart, local option 27check interval, local option 27count reset interval, local option 27max restarts, local option 27min restart time, local option 27service name, local option 27

appserverboxmonitoring 170

appservman 301local options 302not stopping while stopping the application server 300run from conman, process 175

appservman processmonitoring 165

archive settings for job dataconfiguring 54

archived files 223as, global option 13at dependency, job streams without, preventing from starting,

global option 18audit

database and plan 248directory

as log file location 224directory for log files 249dynamic workload scheduling 254enabling 249header format 249initiate 249log files 249log format 250overview 248plan, enabling, global option 18restarting to initiate 249

audit managementaudit history maintenance, global option 13audit store type, global option 13database, enabling, global option 16specify cleanup frequency, global option 20


audit trailsmaintaining 248

auditHistory, global option 13auditStore, global option 13authentication

configure using the Integrated Solutions Console 142federated user registry 140

authentication on SMTP connection, use, global option 22authentication with broker server 197authentication with dynamic domain manager 197authentication, configuring 139authorization with broker server 197authorization with dynamic domain manager 197authorization with master domain manager 197auto link flag 161auto restart, appservman 302automatic maintenance, DB2

administer 226modify policy 226running manually 227switch off 226switch on 227

automatic restart of application server 301automatically grant logon as batch, global option 18autostart monman, local option 27availability 331average run time calculation, weighting factor, global

option 20

Bbacking up

log files 219backup

application server configuration 307backup master domain manager 217log files 217to offline storage 217

backup domain managerchoosing 269configuring 269definition 160domain manager

backup definition 160network security 269performance 322setting up 269switching 270

backup dynamic domain managerchoosing 269

backup master domain managerbacking up files to 217choosing 270configuring 271copying files to 271definition 160extended loss of 272permanent change 272promoting from agent 270setting up 271switching 272

backup master domain manager configuration 56backupConfig, used to backup application server

configuration 307baseRecPrompt, global option 14baseRecPropmt, additional prompts global option 19

batch reportsconfiguring 215

batchmandeadline, minimum wait to check , local option 27dependency status, wait to check, local option 27file, minimum wait to check , local option 27intercom.msg file, maximum wait to read, local option 28processes 162production control file, minimum wait to update, local

option 28starting 163statistics reporting, enable, local option 28status messages, send to standard list, local option 28tuning 318until time, maximum wait to report expiry of, local

option 28batchman process

monitoring 165behind firewall

extended agent 201behindfirewall option 200bindUser, global option 14bm check deadline, local option 27bm check file, local option 27bm check status, local option 27bm check until, local option 28bm look, local option 28bm read, local option 28bm status, local option 28bm verbose, local option 28books

See publicationsbp, global option 14broker backup configuration 273broker components security

defining 197broker configuration

modifying 56broker configuration data 273broker failover 273broker server

limiting access to 197broker server configuration

modifying 56broker server security

defining 197broker switch 273BrokerWorkstation.properties

workload broker workstation configuration 56bu, global option 14

Ccache.dat, increasing size of 297caching mailbox 321calendar, object type, defining access 120, 123calendars, enabling the copying of into Symphony, global

option 19can be event processor, local option 28caonly, SSL auth mode, local option 34carry forward internetwork dependencies, global option 16carry forward resource quantities, global option 16carry forward, global option 15carryStates, global option 14CCLog

shared memory management 318centralized security 105


centralized security, global option 15certificates 184certification authority 185cf, global option 15changeDataSourceProperties script 285changeDataSourceProperties, application server utility 286changeHostProperties script 308changeHostProperties, application server utility 309changeSecurityProperties script 296changeTraceProperties, application server utility 311changing

IP address or host name on the dynamic agent 296IP address or host name on the dynamic workload broker

server 295WebSphere Application Server file 292workstation definition 294workstation host name or IP address 291

check interval, appservman 302check status of remote job, process start 175checkevtptroc, run from conman on a client, process 175checks, file dependency, impacting performance 320ci, global option 16clbox

monitoring 170CLI

default workstation when using, local option 30GSKit certificate keystore label, local option 28GSKit keystore file, local option 28GSKit keystore password file, local option 29host name when connecting from, local option 30is installed as, local option 30OpenSSL certificate file when using SSL with server, local

option 29OpenSSL cipher class, local option 29OpenSSL trusted certificate directory when using SSL with

server, local option 29OpenSSL, enabling SSL server authentication, local

option 29port, local option 34protocol, local option 34proxy port, local option 34proxy, local option 34timeout, local option 38useropts file, local option 38

cli ssl certificate keystore label, local option 28cli ssl cipher, local option 29cli ssl keystore file, local option 28cli ssl keystore pwd, local option 29cli ssl server auth, local option 29cli ssl server certificate, local option 29cli ssl trusted dir, local option 29cn, global option 14command line

See CLIcommand line client

configuring remote access 70command-line prompt

composer 30conman 30

commandsconsole 74dumpsec 103evtsize 172makesec 104optman 7StartUp 164

commands and scripts.jobmanrc 177altpass 274appservman 301backupConfig 307changeDataSourceProperties 285changeHostProperties 308changeSecurityProperties 296dbexpand, impact on audit log file 252dbreorg 228dbrunstats 227evtsize

to monitor queue sizes 169jobmanrc 177link 161makesec, impact on audit log file 252restoreConfig 307rmstdlist 223startappserver 301, 303StartUp 163startWas 300stopappserver 301, 303stopWas 300unlink

usage 161updateWas 306updateWasService 305

communications in the network 160companyName, global option 14composer

defining access for working with objects 120prompt, local option 30

configurationDynamic Workload Console 83for LDAP 87for single sign-on 87ldap user registry 83user 84user's portfolio 84

configuration file, netman 175configuration files

application server, backup and restore 307backing up 218

configureauthentication using the Integrated Solutions Console 142Tivoli Workload Scheduler to use LDAP 201

configuringarchive settings for job data 54authentication 139global resource matching 52heartbeat signal 52J2EE communication channel 59J2EE jobs 59maximum number of results for global resource

matching 52time interval for job allocation to resources 52time interval for notifications on resources 52time interval for retrying failed operations 54WebSphere Application Server 59

configuring Dynamic Workload Consoleglobal settings file 92settings repository 97

configuring reportsDB2 database 97Oracle database 98

conmandefining access for working with objects 120

Index 339

conman (continued)log type 250prompt, local option 30running appservman 175running checkevtptroc on a client 175running deployconf 175running startappserver 175running startevtptroc 175running stopappserver 175running stopevtptroc 175running stopevtptroc on a client 175running stopmon 175running switchevtptroc 175starting the find and return of a stdlist file 175

connection failed, wait to retry in netman, local option 33connection parameters

configuring 70connection to broker server

establishing 197connectivity, impact on network 166connector

refresh after changing auditing parameters 249console command 74console manager, start process 176console messages and prompts 73continue keyword 137conventions used in publications xiicopying files to backup master domain manager 271count reset interval, appservman 303courier

monitoring 170courier.msg file, wait to read in jobman, local option 31cpu, object type, defining access 120cpu, SSL auth mode, local option 35critical agents, positioning 166critical path processing, enabling, global option 19cross dependencies notification

timeout 21cs, global option 14custom, authentication 140customer support

See Software Supportcustomization 7

Dda, global option 16data flows, planning for 168data maintenance 217data volumes, impact on network 166database

back upto backup master domain manager 217to offline storage 217

directory for audit files 249log type 250maintenance 217migrating from DB2 to Oracle and vice versa 233name, change 285reorganization 219

database and plan audit 248database audit enabling, global option 16database job

configuring 66date format, local option 30DB2

administrative tasks 225

DB2 (continued)automatic maintenance


changing database user password 274database name, change 285host name, change 285increase maximum log capacity 325migrating to Oracle 233monitoring the lock list memory 229passwords not used by TWS, changing 225port, change 285reorganization 219reorganize database 228tools, locating 225tuning 319user permissions for running the tools 226

DB2 configurationIBM Global Security Kit (GSKit) libraries 209

DB2 databaseconfiguring reports 97

DB2, version 9.5FIPS compliance 209

DB2, version 9.7, fix pack 2 and laterFIPS compliance 211

dbexpand, command, impact on audit log file 252dbreorg, DB2 tool 228dbrunstats, DB2 tool 227DDM secure connection 197deadline, minimum wait to check , local batchman option 27deadlineOffset, global option 14default ws, local option 30definition

workstation changing 294dependency checks, file, impacting performance 320dependency status, batchman wait to check, local option 27deploymentFrequency, global option 15deplyconf, run from conman, process 175df, global option 15direct scheduling

J2EE jobs 59directories

audit 224, 249database 249logs 223methods 224plan 249schedForecast 224schedlog 223schedTrial 224stdlist 224tmp, as location for temporary files 225traces 223

disk fillingmonitoring 221

disk fullmonitoring 221

disk spacemaintaining enough available space 220monitoring 221used by backup domain manager impacting

performance 323dm.msg message queue 169do, global option 14


domaindefinition 160master, definition 160parent, definition 160structure of, impact on critical agents 166

domain managerbackup

See backup domain managerbackup master

See backup master domain managerdata flows 168, 169definition 160failure 269IP address validation 181log file maintenance 223loss of 269master

See master domain managermitigating loss of 269network planning, role of 166optimizing for critical activities 166positioning for critical activities 166role of in network planning 166running without 269switching 270temporary files 225without 269

domain user, resolving account in Windows 331download scripts from z/OS master domain manager, starting

process 175DsGetDcName, API used to resolve Windows user ID

account 331dumpsec command 103duration, job, long, threshold, global option 20dynamic agent

changing IP address or host name 296dynamic agent configuration 56dynamic agent logs encoding 43dynamic agent logs setting 43dynamic domain manager

configuring the dynamic workload broker server 49defining broker connection 197defining SSL connection 197maintaining the dynamic workload broker server 50

dynamic domain manager configuration 56dynamic workload broker

start 298stop 298

dynamic workload broker securityworkload broker security roles and users and groups 67

dynamic workload broker serverchanging IP address or host name 295changing URI data 50configuring 49exportserverdata 50http communication 51https communication 51importserverdata 50maintaining 50unsecure communication 51

dynamic workload broker server on dynamic domain managerconfiguring 49maintaining 50

dynamic workload broker server on master domain managerconfiguring 49maintaining 50

Dynamic Workload Consoleaccessibility xiiauthentication method 83configuration 77, 83configure to view reports 97launch in context 77local OS method 83multiple production plan reports, affecting

performance 328PAM authentication method 83

Dynamic Workload Console authentication methodconfiguring 83

Dynamic Workload Console SSL securitykeystore passwords 193

dynamic workload scheduling audit 254

Eed, global option 16education xiiee, global option 19eh, global option 17EIF event queue, increasing size of 297empty job streams, global option 16enable list security check 17enCarryForward, global option 15enCentSec, global option 15enCFinterNetworkDeps, global option 16enCFResourceQuantity, global option 16encrypting application server profile properties 305encryption cipher classes

EXP 29EXPORT40 29HIGH 29LOW 29MD5 29MEDIUM 29NULL 29SSLv3 29TLSv 29

encryption, strong, enabling, global option 19enDbAudit, global option 16, 249enEmptySchedsAreSucc, global option 16enEventDrivenWorkloadAutomation, global option 16enEventProcessorHttpsProtocol, global option 17enExpandedResources, global option 17enForecastStartTime, global option 17engine

administrative tasks 267enLegacyId, global option 17enLegacyStartOfDayEvaluation, global option 17enListSecChk, global option 17enLogonBatch, global option 18enPlanAudit, global option 18, 249enPreventStart, global option 18enRetainNameOnRerunFrom, global option 18enSSLFullConnection, global option 18enStrEncrypt, global option 19enSwfaultTol, global option 19Enterprise Workload Manager

resource assignment 54resource optimization 54resource weight 54retry on failure 54

enTimeZone, global option 19enWorkloadServiceAssurance, global option 19er, global option 17

Index 341

error messagesIP address validation 180

es, global option 16event processor

managing 297event processor HTTPS protocol, global option 17event processor, enabling workstation to be, local option 28event rule management

log history maintenance, global option 13, 20mail sender name, global option 21SMTP

port, global option 22server name, global option 22use authentication, global option 22use SSL, global option 22use TLS, global option 23user name, global option 22user password, global option 22

specify cleanup frequency, global option 20TEC server

name, global option 23port, global option 23

event-driven workload automation enablement, globaloption 16

event, ApplicationServerStatusChanged 305event, object type, defining access 125eventProcessorEIFPort, global option 19eventrule, object type, defining access 120evtsize command 172evtsize, command

to monitor queue sizes 169EXP, encryption cipher class 29EXPORT40, encryption cipher class 29exportserverdata 50extended agent

behind firewall 201definition 160jobs cannot launch 179overview 176

extRecPrompt, global option 19

Ffailure of

domain manager 269dynamic domain manager 269master domain manager 270

fault tolerant switch manager, enabling, global option 19fault-tolerant agent

backing up to, when used as backup master domainmanager 217

data flows 169definition 160promoting to backup master domain manager 270

fault-tolerant agent instancesautomatic initialization 299

fault-tolerant domain managerSee domain manager

fault-tolerant switch managerSee domain manager

fault-tolerant switch manager, impact on performance 322federated user registry 140file dependency checks impacting performance 320file registry, authentication 140file sets

See files

file systemSee files

file, object type, defining access 125files

.rhost 177archived 224avoiding full file systems 220batchman minimum wait to check , local option 27configuration

backing up 218forecast plan logs 224host.equiv 177job output, archived 224localopts 23log files

backing up 217maintaining file system 220NetConf 175Security

backing up 218Symphony

archived 223IP address validation 179maximum number of records 176overview 160scanning by batchman 162

temporarySee temporary files

trial plan logs 224useropts 41

filling mailboxesmonitoring 170

filling message queuesmonitoring 170

final job stream, launch time, global option 23FIPS compliance 201

configuring batch reports 215database configuration 209DB2, version 9.5 209DB2, version 9.7, fix pack 2 and later 211EIF Listener port 209embedded WebSphere Application Server 207enabling using local option 36FIPS certificates 202localopts parameters 207

firewall bypass, starting 175firewall support 200flows, data, planning for 168forecast plan logs 224forecast start time enablement, global options 17format, audit log files 250fta.msg message queue 169ftdown message queue, in backup domain manager 323ftup message queue, in backup domain manager 323full file systems, avoiding 220FullStatus mode, setting 162

Ggetaddrinfo() system call 179global option descriptions

approachingLateOffset 13auditHistory 13auditStore 13baseRecPrompt 14bindUser 14carryforward 15


global option descriptions (continued)carryStates 14companyName 14deadlineOffset 14deploymentFrequency 15enCentSec 15enCFinterNetworkDeps 16enCFResourceQuantity 16enDbAudit 16enEmptySchedsAreSucc 16enEventDrivenWorkloadAutomation 16enEventProcessorHttpsProtocol 17enExpandedResources 17enForecastStartTime 17enLegacyId 17enLegacyStartOfDayEvaluation 17enListSecChk 17enLogonBatch 18enPlanAudit 18enPreventStart 18enRetainNameOnRerunFrom 18enSSLFullConnection 18enStrEncrypt 19enSwfaultTol 19enTimeZone 19enWorkloadServiceAssurance 19eventProcessorEIFPort 19extRecPrompt 19ignoreCals 19logCleanupFrequency 20logHistory 20logmanMinMaxPolicy 20logmanSmoothPolicy 20longDurationThreshold 20mailSenderName 21maxLen 21minLen 21nt 21promotionOffset 21smtpServerName 22smtpServerPort 22smtpUserName 22smtpUserPassword 22smtpUseSSL 22smtpUseTLS 23startOfDay 23statsHistory 23TECServerName 23TECServerPort 23useAuthentication 22

global optionsoptman command line 7time zone feature 75

global resource matchingconfiguring 52

global settingsconfiguration 92

glossary xiiGSKit

certificate keystore label, local option 28, 35keystore file, local option 28keystore password file, local option 29SSL keystore file, local option 36SSL keystore password file, local option 36

Hheader format, audit log records 249header, log type 250heap size, application server, increase 324heartbeat signal

configuring 52HIGH, encryption cipher class 29history, job statistics, global option 23host name

application server, modify 308changing on the dynamic agent 296changing on the dynamic workload broker server 295database, change 285impact of changing 181

host name or IP addresschanging 291changing WebSphere Application Server file 292

host, for extended agents, definition 160host, when connecting from command line client, local

option 30host.equiv, file 177HTTPS protocol for event processor, global option 17

IIBM Global Security Kit (GSKit) libraries

DB2 configuration 209IBM Tivoli Directory Server 140IBMWAS61Service 302ic, global option 19ignoreCals, global option 19importserverdata 50incoming message cache

enable in mailman, local option 32resize in mailman, local option 32

indirect schedulingJ2EE jobs 59

installationchecking

See installation, verifyingdirectory 1steps

See steps, installationinstance initialization 299instances

automatic initialization 299Integrated Solutions Console

configure authentication 142intercom

monitoring 170intercom.msg file, batchman maximum wait to read, local

option 28Intercom.msg message queue 169interface SSL security

keystore passwords 193internal Symphony table, determining the size of 176IP address

changing on the dynamic agent 296changing on the dynamic workload broker server 295impact of changing 181support for V6 179validation 179

is remote cli, local option 30ISMP

See InstallShield wizard

Index 343

JJ2EE communication channel

configuring 59J2EE job

configuring 66J2EE jobs

configuration for 59configuring 59direct scheduling 59enabling 59indirect scheduling 59JMS 59security settings 59supported operations 59WebSphere Application Server settings 59

J2EE jobs on agentconfiguration 60, 62, 63

J2EEJobExecutorConfig.propertiesconfiguring 60

J2SESee Java Runtime Environment

Java 2 Platform, Standard EditionSee Java Runtime Environment

Java development kitSee Java Runtime Environment

Java Development KitSee Java Runtime Environment

Java heap size, application server, increase 324Java job

configuring 66Java Virtual Machine

See Java Runtime EnvironmentJava Virtual Machine options 47JDBC driver, resolving problems 289JDK

See Java Runtime Environmentjm job table size, local option 30jm look, local option 30jm nice, local option 30jm no root, local option 30jm promoted nice, local option 30jm promoted priority, local option 31jm read, local option 31JMS

J2EE jobs 59JnextPlan

impact on auditing 249when setting up a domain manager 271

JnextPlan, avoiding lock list memory problmes 229job executors

configuring 66Java options 47

job management tasks wait in jobman, local option 30job output files, archived 224job plug-ins

configuring 66Java options 47

job status change notificationtimeout 21

job streamsempty. behavior, global option 16more than 180 000, impacting DB2 log files 323naming in mixed environments, global option 17without at dependency, preventing from starting, global

option 18without jobs. behavior, global option 16

job submissions, manual, impacting performance 320

job table, size of in jobman, local option 30job times, minimum and maximum, logging and reporting,

global option 20job types with advanced options

authorization for running 120configuration files 66configuring 66cpu access 120customizing 66defining access 120defining authorization 120Java options 47

job types with advanced options configuration fileslocation 66

job, object type, defining access 120, 125JobDispatcherConfig.properties

job age in archive database 54job age in database 54

jobmantuning 318

jobman and JOBMANcourier.msg file, wait to read, local option 31job management tasks wait, local option 30launching by batchman 162nice value to apply to critical UNIX or Linux jobs, local

option 30nice value to apply to UNIX or Linux jobs, local option 30priority value to apply to critical Windows jobs, local

option 31root jobs, enabling the launch of, local option 30size of job table, local option 30starting 163

jobman processmonitoring 165

jobmanrc 177jobs

failing to launch on extended agent 179improving processing performance 320late, when becoming, global option 13long duration threshold, global option 20more than 40 000, impacting Java heap size 323promotion of critical, eligibility for, global option 21retaining name on rerun, global option 18statistics history, global option 23

JRESee Java Runtime Environment

JVMSee Java Runtime Environment

JVM options 47

Llate jobs, when becoming, global option 13launch in context

Dynamic Workload Console 77lb, global option 18lc, global option 20ld, global option 20LDAP

authentication 140configuration 87configure Tivoli Workload Scheduler to use 201

ldap user registryconfiguration 83

le, global option 17lh, global option 20li, global option 17


Lightweight Directory Access ProtocolSee LDAP

link command, using 161link flag, auto 161link to non-responding workstation, wait to retry in mailman,

local option 32linking

concept 161Linux

jobs, nice value to apply when critical, local option 30jobs, nice value to apply, local option 30

list permissionenable option 17

lm, global option 20local option descriptions

appserver auto restart 27appserver check interval 27appserver count reset interval 27appserver max restarts 27appserver min restart time 27appserver service name 27autostart monman 27bm check file 27bm check status 27bm check until 28bm look 28bm read 28bm stats 28bm verbose 28can be event processor 28caonly 34cli ssl certificate keystore label 28cli ssl cipher 29cli ssl keystore file 28cli ssl keystore pwd 29cli ssl server auth 29cli ssl server certificate 29cli ssl trusted dir 29composer prompt 30conman prompt 30cpu 35date format 30default ws 30host 30is remote cli 30jm job table size 30jm look 30jm nice 30jm no root 30jm promoted nice 30jm promoted priority 31jm read 31local was 31merge stdlists 32mm cache mailbox 32mm cache size 32mm read 32mm resolve master 32mm response 32mm retry link 32mm sound off 32mm symphony download timeout 32mm unlink 32mozart directory 33nm mortal 33nm port 33nm read 33

local option descriptions (continued)nm retry 33nm SSL full port 33nm SSL port 33parameters directory 34port 34protocol 34proxy 34proxy port 34restricted stdlists 34SSL auth mode 34SSL auth string 35SSL CA certificate 35SSL certificate 35ssl certificate keystore label 35SSL encryption cipher 35SSL FIPS enabled 36SSL key 36SSL key pwd 36SSL keystore file 36SSL keystore pwd 36SSL random seed 36stdlist width 37string 35switch sym prompt 37sync level 37syslog local 37tcp connect timeout 37tcp timeout 37this cpu 37timeout 38unison network directory 38useropts 38wr enable compression 38wr read 38wr unlink 38

local optionsfile example 24file template 24setting 23setting sysloglocal 74syntax 23

local OS on Dynamic Workload Consoleconfiguring 83

local OS on TDWCconfiguring 83

local OS, authenticationfor Tivoli Dynamic Workload Console on UNIX operating

systems 140local security 101local user, resolving account in Windows 331local was, local option 31localopts

nm ipvalidate 179option for setting synch level 322options for caching mailbox messages 321options used for tuning 318parameters for tuning mailman servers 174tuning for job-processing performance 320used for appservman 302

localopts file 23lock list memory, DB2, monitoring 229LOCKLIST, DB2 configuration parameter 229log capacity, DB2, increase 325log configuration

Tivoli Workload Scheduler agent 43

Index 345

log filesaudit

format 250location 249

backing up 219backup 217maintenance 223

logCleanupFrequency, global option 20LOGFILSIZ, DB2 parameter 326logging, impact on performance 318logging.properties

configuring 62logHistory, global option 20logmanMinMaxPolicy, global option 20logmanSmoothPolicy, global option 20logon as batch, granting automatically, global option 18LOGPRIMARY, DB2 parameter 326logs

dynamic agent encoding 43logs directory, as log file location 223LOGSECOND, DB2 parameter 326longDurationThreshold, global option 20LookupAccountName, API used to resolve Windows user ID

account 331loss of


LOW, encryption cipher class 29lt, global option 20LTPA keys

sharing 87LTPA token_keys

using the same 88

Mmailbox

monitoring 170mailbox caching 321mailbox files

setting size 172mailbox full

monitoring 170Mailbox.msg

message queue 169mailboxes

monitoring 170mailman

$MASTER variable, resolve, local option 32caching 321determining the size of its internal Symphony table 176incoming message cache

enable, local option 32resize, local option 32

link to non-responding workstation, wait to retry, localoption 32

processes timing out 161servers

configuring to maximize critical activities 166tuning 174

starting 163, 175starting with demgr parameter 175tellop command, respond to, local option 32tuning 318unlink non-responding workstation, wait to, local

option 32

mailman (continued)wait for connection, local option 32workstation not responding, wait to report, local

option 32mailman process

monitoring 165mailSenderName, global option 21maintenance

database 217DB2, automatic


Oracle database 232makesec

impact on audit log file 252log type 250

makesec command 104manual job submissions impacting performance 320manuals

See publicationsmaster domain manager

backing up to backup master domain manager 217backup

See backup master domain managerconfiguring the dynamic workload broker server 49defining broker connection 197defining SSL connection 197definition 160extended loss of 272failure 270loss of 270maintaining the dynamic workload broker server 50mitigating loss of 270permanent change 272running without 270switching 272without 270

master domain manager configuration 56master domain, definition 160master instances

automatic initialization 299max restarts, appservman 303maximum and minimum job times, logging and reporting,

global option 20maximum number of results for global resource matching

configuring 52maximum records in Symphony file 176maxLen, global option 21MAXLOCKS, DB2 configuration parameter 229MD5, encryption cipher class 29MEDIUM, encryption cipher class 29memory

management by logging processes impactingperformance 318

merge stdlists, local option 32message caching 321message level 74message queues

dm.msg 169fta.msg 169ftdown, in backup domain manager 323ftup, in backup domain manager 323in backup domain manager 323Intercom.msg 169


message queues (continued)Mailbox.msg 169monitoring 170tomaster.msg 169

methods directory, as log file location 224Microsoft Windows Active Directory 140migration

of database (DB2 to Oracle and vice versa) 233min restart time, appservman 302minimum and maximum job times, logging and reporting,

global option 20minLen, global option 21mitigating loss of


mixed environments, naming of job streams in, globaloption 17

ml, global option 21mm cache mailbox, local option 32mm cache size, local option 32mm read, local option 32mm resolve master, local option 32mm response, local option 32mm retry link, local option 32mm sound off, local option 32mm symphony download timeout, local option 32mm unlink, local option 32Mm_unlink, localopts parameter 174monbox

monitoring 170moncmd

monitoring 170monman

autostart, local option 27starting process 175

monman processmonitoring 165

mozart directory, local option 33ms, global option 21

Nname, TEC server, global option 23naming, of job streams in mixed environments, global

option 17NetConf, file 175NetGetAnyDCName, API used to resolve Windows user ID

account 331netman

configuration file 175connection failed, wait to retry, local option 33IP address validation 179port, local option 33quit when child processes stopped, local option 33SSL full port, local option 33SSL port, local option 33starting 163stop and start commands, wait to check for, local

option 33support for Internet Protocol version 6 179

netman processmonitoring 165

NetUserGetInfo, API used to resolve Windows user IDaccount 331

networkcapacity 166

network (continued)changes, impact of 181communications 160impact of changes 181IP address validation 179linking 161message queues, planning for 168monitoring for unlinked workstations 161operation 162optimizing 166overview 159processes 163structure, impact on critical agents 166support for Internet Protocol version 6 179traffic caused by backup domain manager impacting

performance 323unlinking 161

network traffic 317new executors

authorization for running 120defining access 120defining authorization 120

nice value to apply to critical UNIX or Linux jobs in jobman,local option 30

nice value to apply to UNIX or Linux jobs in jobman, localoption 30

nm ipvalidate, localopts parameter 179nm mortal, local option 33nm port, local option 33nm read, local option 33nm retry, local option 33nm SSL full port, local option 33nm SSL port, local option 33nodename validation 179normal run time calculation, weighting factor, global

option 20notificationTimeout, global option 21nt, global option 21NULL, encryption cipher class 29

Oobject types, defining access to composer actions 120offline storage, used for backup and restore 217opens, file dependency 177OpenSSL

ca certificate file, local option 35certificate file, local option 35cipher class, local option 29enabling SSL server authentication, local option 29server certificate when using command-line client, local

option 29SSL encryption cipher, local option 35SSL key file, local option 36SSL key password file, local option 36SSL random seed, local option 36trusted directory when using command-line client, local

option 29options, global 7optman

security settings 7optman, enabling audit 249Oracle

administrative tasks 231changing user password 274database name, change 285host name, change 285

Index 347

Oracle (continued)maintaining database 232migrating to DB2 233obtaining database information 232passwords not used by TWS, changing 232port, change 285reorganization 219running maintenance manually 232tools, locating 232tuning 319user permissions for running the tools 233

Oracle databaseconfiguring reports 98

Ppa, global option 18parallel database migration (DB2 to Oracle and vice

versa) 233parameter, object type, defining access 128parameters directory, local option 34parent domain, definition 160parms, log type 251password for SMTP connection, global option 22passwords

other DB2, changing 225TWS_user, changing 274

performancefault-tolerant switch manager 322file dependency checks, too many 320impacted by multiple TDWC production plan reports 328job submissions, manual, too many 320job-processing, improving 320network 166too many file dependency checks 320too many manual job submissions 320tuning job processing on a workstation 318tuning on UNIX 318workload spreading 320

permissions, userfor running DB2 tools 226for running Oracle tools 233

plan auditing, enabling, global option 18plan directory for audit files 249plan, log type 251plan, preproduction, maximum length, global option 21plan, preproduction, minimum length, global option 21planned maintenance

See maintenanceplanning to minimize network message queues 168Pluggable Authentication Module, using in TWS 157po, global option 21pobox

monitoring 170port

SMTP server, global option 22SSL full , used by netman, local option 33SSL, used by netman, local option 33TEC server, global option 23

port for command line client, local option 34port number, event processor, global option 19port, database, change 285port, for netman, local option 33preproduction plan, maximum length, global option 21preproduction plan, minimum length, global option 21preventing job streams without at dependency from starting,

global option 18

priority value to apply to critical Windows jobs in jobman,local option 31

private keys 184problems

See troubleshootingprocess messages 73process prompts 73processes status

monitoring 165production control file, batchman minimum wait to update,

local option 28production plan reports, TDWC, affecting performance 328production, managing on extended agents 179profile properties, application server, encrypting 305promoting an agent to backup master domain manager 270promoting to backup master domain manager 270promotion of critical jobs, eligibility for, global option 21promotionOffset, global option 21prompt, object type, defining access 120, 129prompts, additional, global option 19properties

of application server, utilities for changing 312protocol, local option 34proxy port, local option 34proxy, local option 34ps, global option 18publications xii

Qqueues, message

See message queuesquit netman when child processes stopped, local option 33

Rr3batch extended agent, interaction process start 176RACF, authentication 140reconfiguration of database (DB2 to Oracle and vice

versa) 233release, log type 251remote access for command-line, configuring 70remote job, check status of, process start 175remove

See uninstallationreorganize DB2 database 228reorganizing database 219report, object type, defining access 130reports configuring

DB2 database 97Oracle database 98

reports, configuring Dynamic Workload Console to view 97required maintenance

See maintenancererun jobs, retaining name, global option 18resource access, global option 17resource advisor agent 273resource quantities carried forward, global option 16resource, object type, defining access 120, 130restart, automatic, of application server 301restore

application server configuration 307restore of application server configuration 307restore, from offline storage 217restoreConfig, used to restore application server

configuration 307


restricted stdlists, local option 34restricting access to broker server 197RHEL

See Red Hat Enterprise Linuxrights, user

for running DB2 tools 226for running Oracle tools 233

rmstdlist commandused for archiving log files 223

role-based authorization with broker server 197roles

for Tivoli Dynamic Workload Broker 87for Tivoli Workload Scheduler 85

root jobs, enabling the launch of in jobman, local option 30root user, changing password 274rq, global option 16rr, global option 18run time (average) calculation, weighting factor, global

option 20running without


Ssample audit log entries 253sc, global option 17scalability 323schedlog directory, as log file location 223schedule, object type, defining access 120, 130schedules

See job streamsscheduling events, communications 160script

webui 99scripts

See commands and scriptssd, global option 23se, global option 19security

centralized 105information, verifying in Windows 331local 101network, for backup domain manager 269overview 101specifying accesses 119specifying object types 113specifying objects 114specifying user attributes 108template file 106

security check when listing, global option 17security file

enabling centralized security, global option 15security file, template 106security level

enabled 187force 187on 187

security settings, application server, modify 296Security, file

backing up 218sender name, mail, event rule management, global option 21server

monitoring 170server configuration

ResourceAdvisorConfig.properties file 52

serversmailman

configuring to maximize critical activities 166tuning 174

serviceWindows

for the application server, updating 305service name, appservman 303services

IBMWAS61Service 302services (Windows)

changing password 274for application server, update 305stopping 283Tivoli Workload Scheduler, configuring in NetConf

file 175setting the local options 23setting the user options 41settings repository

configuration 97sf, global option 18sh, global option 23showDataSourceProperties, application server utility 286showHostProperties, application server utility 309single sign-on

configuration 87LTPA token_keys 88

sizing the internal Symphony table 176SMTP

authentication on connection, use, global option 22port, global option 22server name, global option 22SSL on connection, use, global option 22TLS on connection, use, global option 23user name for connection, global option 22user password for connection, global option 22

smtpServerName, global option 22smtpServerPort, global option 22smtpUseAuthentication, global option 22smtpUserName, global option 22smtpUserPassword, global option 22smtpUseSSL, global option 22smtpUseTLS, global option 23sn, global option 22soap.client.props

configuring 63sp, global option 22space, disk

See disk spaceSSL

authentication mode, local option 34authentication string, local option 35full connection enablement, global option 18full port, used by netman, local option 33GSKit keystore file when using command-line client, local

option 28GSKit keystore label when using command-line client, local

option 28GSKit keystore password file when using command-line

client, local option 29GSKit, certificate keystore label, local option 35GSKit, SSL keystore file, local option 36GSKit, SSL keystore password file, local option 36OpenSSL CA certificate file, local option 35OpenSSL certificate file for communications with

command-line client, local option 29OpenSSL certificate file, local option 35

Index 349

SSL (continued)OpenSSL cipher class when using command-line client,

local option 29OpenSSL trusted certificate directory for communications

with command-line client, local option 29OpenSSL, enabling server authentication for command line

client, local option 29OpenSSL, SSL encryption cipher, local option 35OpenSSL, SSL key file, local option 36OpenSSL, SSL key password file, local option 36OpenSSL, SSL random seed, local option 36port, used by netman, local option 33

SSL attributesconfiguring 187

SSL auth mode, local option 34SSL auth string, local option 35SSL CA certificate, local option 35ssl certificate keystore label, local option 35SSL certificate, local option 35SSL communication

enabled 187force 187on 187

SSL encryption cipher, local option 35SSL FIPS enabled, local option 36SSL key pwd, local option 36SSL key, local option 36SSL keystore file, local option 36SSL keystore pwd, local option 36SSL on SMTP connection, use, global option 22SSL random seed, local option 36SSL security

HTTP/HTTPS 183keystore passwords 193overview 183RMI/IIOP 183topology connection 183

SSL supportconfiguring 188

SSLv3, encryption cipher class 29st, global option 17stageman, log type 251standard agent instances

automatic initialization 299standard agent, definition 160start dynamic workload broker 273, 298start-of-plan-period

initialization, communications 160startappserver 301, 303

run from conman, process 175startevtptroc, run from conman, process 175starting the application server 300startOfDay, global option 23startOfDay, how evaluated in time zones, global option 17StartUp

used for starting netman 163StartUp command 164startWas command 300statistics reporting by batchman, enable, local option 28statsHistory, global option 23status

application server 304status messages, batchman send to standard list, local

option 28stdlist directory

information about extended agent jobs 177maintaining 224

stdlist width, local option 37stdlist, merge console messages into, local option 32stop and start commands, wait to check for in netman, local

option 33stop dynamic workload broker 273, 298stopappserver 301, 303

configure user credentials 304run from conman, process 175

stopevtptroc, run from conman on a client, process 175stopevtptroc, run from conman, process 175stopmon, run from conman, process 175stopping

services 283stopping the application server 300stopping workstations hierarchically, starting process 175stopWas command 300streamlogon, user 331string, SSL auth mode, local option 35strong encryption, enabling, global option 19structure of network, impact on critical agents 166submitting too many jobs manually, impact on

performance 320Sun

See SolarisSun Java System Director Server 140Sun One 140sw, global option 19switch dynamic workload broker instances 273switch manager, fault tolerant, enabling, global option 19switch manager, fault-tolerant

See backup domain managerswitch sym prompt, local option 37switchevtptroc, run from conman, process 175switching a domain manager, short-term 270switching a master domain manager

long-term 272short-term 272

switching extended agents$manager keyword 112$master keyword 112

switching standard agents$manager keyword 112$master keyword 112

switching the dynamic domain managerbroker instance switch 273

switching the dynamic workload broker 273switching the master domain manager

broker instance switch 273switchmgr

starting normal process 175starting process so that links are not started until event

received 175Symphony file

archived 223enabling the copying of calendars into, global option 19IP address validation 179maximum number of records 176monitoring space used 220overview 160scanning by batchman 162support for Internet Protocol version 6 179

Symphony file download timeout, local option 32Symphony table, internal, determining the size of 176sync level, local option 37synch level option, setting 322syslog 73syslog local, local option 37


sysloglocal optionsLOG_ERR 74LOG_INFO 74LOG_NOTICE 74LOG_WARNING 74

Ttask executors

configuring 66tcp connect timeout, local option 37tcp timeout, local option 37TCP/IP ports, application server, modify 308TDWC authentication method

configuring 83technical training xiiTECServerName, global option 23TECServerPort, global option 23tellop command, respond to in mailman, local option 32temporary files 225text files, used for backup and restore

See filesth, global option 23this cpu, local option 37threshold, long job duration, global option 20time interval for job allocation to resources

configuring 52time interval for notifications on resources

configuring 52time interval for retrying failed operations

configuring 54time zone feature, enabling, global option 19time zones

evaluating startOfDay, global option 17timeout, local option 38Tivoli Dynamic Workload Broker

roles 87Tivoli Dynamic Workload Console

configuration 77defining access for working with objects 120modifying 83

Tivoli technical training xiiTivoli Workload Automation

hone installation path 2instance 1

Tivoli Workload Schedulerinstallation path 2preventing access 99roles 85security file 86

Tivoli Workload Scheduler agentlog configuration 43trace configuration 44

Tivoli Workload Scheduler agent tracesmodifying 45viewing settings 45

Tivoli Workload Scheduler connector SSL securitykeystore passwords 193

Tivoli Workload Scheduler instancesautomatic initialization 299Tivoli Workload Scheduler service 299

Tivoli Workload Scheduler to use LDAPconfigure 201

tl, global option 23TLS on SMTP connection, use, global option 23TLSv, encryption cipher class 29tmp directory, as location for temporary files 225

TokensrvSee Tivoli Token Service

tomastermonitoring 170

tomaster.msg message queuedata flow 169in backup domain manager 323

toolsdatabase and plan 248dynamic workload scheduling 254

tp, global option 23trace configuration

Tivoli Workload Scheduler agent 44traces directory, as trace file location 223tracing 317traffic caused by backup domain manager impacting

performance 323training

technical xiitree structure, impact on critical agents 166trial plan logs 224troubleshooting

data flows 168message queues 168

ts, global option 15tuning

database 319job processing on a workstation 318localopts file, for job-processing performance 320mailman servers 174the application server 319UNIX operating systems 318

TWA_home 1TWS disk space

monitoring 221TWS processes status

monitoring 165TWS_user

changing password 274owning processes 163required security access for workload service

assurance 133TWSObjectsMonitor events,

ApplicationServerStatusChanged 305tz, global option 19

Uua, global option 22un, global option 22unison network directory, local option 38UNIX

changing passwords on 274configuration for IP address validation 180extended agents 177jobs, nice value to apply when critical, local option 30jobs, nice value to apply, local option 30temporary directory, on UNIX, access rights 331tuning 318updating SOAP properties after changing application

server user or password 306unixlocl, access method 177unixrsh, access method 177unixssh, access method 177unlink non-responding workstation, wait to in mailman, local

option 32

Index 351

unlink, commandusage 161

unlinkingconcept 161workstations 283

until time, batchman maximum wait to report expiry of, localoption 28

up, global option 22updateWas, using to update the SOAP properties after

changing application server user or password 306updateWasService

using to update the application server Windowsservice 305

us, global option 22use LDAP

configure Tivoli Workload Scheduler to 201used disk space

monitoring 221user

configuration 84portfolio 84

user name for SMTP connection, global option 22user options

setting 41syntax 41

user password for SMTP connection, global option 22user permissions

for running DB2 tools 226for running Oracle tools 233

user securitycommands

dumpsec 103makesec 104

local security 101security file

access capabilities 119modifying 102sample 133syntax 106user qualification 111variables 118wildcards 108

security files 102setting 101

userobj, object type, defining access 120, 131useropts file 41useropts, local option 38users

domain, resolving account in Windows 331local, resolving account in Windows 331streamlogon 331

utilitiesapplication server 313changeDataSourceProperties 286changeHostProperties 309changeTraceProperties 311defining access for working with objects 120showDataSourceProperties 286showHostProperties 309

utilities that change application server properties, using 312utility commands

setting mailbox file size 172starting up netman 164

Vvalidating IP address 179

variables$MASTER, resolve, local option 32

vartable, object type, defining access 132volumes, data, impact on network 166

Wwa, global option 19wait for connection in mailman, local option 32warning messages

IP address validation 180Web User Interface

See Dynamic Workload ConsoleWebSphere Application Server

See also application serverconfiguring 59

WebSphere Application Server filechanging host name or IP address 292

webuiscript 99

weighting factor for calculating average run time, globaloption 20

Windowschanging passwords on 274jobs, nice value to apply when critical, local option 31resolving user ID account 331service

for the application server, updating 305Windows OS

special characters, handling 73without


workloadspreading to improve performance 320

workload automation, event-driven, enablement, globaloption 16

workload broker users and rolesmapping security roles in Websphere Application

Server 67modifying 67

workload broker workstation configurationmodifying 56

workload service assuranceapproaching late offset, global option 13deadline offset, global option 14jobs eligible for promotion, global option 21nice value to apply to critical UNIX or Linux jobs in

jobman, local option 30priority value to apply to critical Windows jobs in jobman,

local option 31required security access for TWS_user 133

workload service assurance, enabling, global option 19workstation

application server status 304changing host name or IP address 291Tuning job processing on 318

workstation definitionchanging 294

workstation not responding, wait to report in mailman, localoption 32

workstationsdefault when using the command line client, local

option 30enabling to be event processor, local option 28unlinking 283


wr enable compression, local option 38wr read, local option 38wr unlink, local option 38Wr_unlink, localopts parameter 174writer

starting 163starting, for incoming mailman messages 175stopping, for incoming mailman messages 175

wsadmin utility 285

Xxl, global option 21xp, global option 19

Zz/OS Integrated Security Services LDAP Server 140

Index 353

��

Product Number: 5698-WSH

Printed in USA

SC23-9113-03

Spineinformation:

IBM

Tivo

liW

orkl

oad

Sche

dule

rVe

rsio

n8.

6Ad

min

istra

tion

Guid

e��

�