Cybermation ESP: dSeries
Release 5.0
Administrator’s Guide
ESPD-5.0-AG-01 First Edition (April 2006) This edition applies to Cybermation ESP: dSeries Release 5.0. The software and related manuals are protected by copyright law. Cybermation ESP: dSeries documentation © Copyright 2006 Cybermation International Distribution SRL All rights reserved. No portion of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means without the express written permission of Cybermation International Distribution SRL www.cybermation.com U.S. Government Users. RESTRICTED RIGHTS - Use, duplication or disclosure restricted by the GSA ADP Schedule Contract with Cybermation USA, Inc., a subsidiary of Cybermation International Distribution SRL.
Trademark Notice Cybermation, ESP Workload Manager, and ESP Espresso are registered trademarks of Cybermation, Inc. ESP Alchemist is a registered trademark of Cybermation International Inc. ESP System Agent and ESP Business Agent are trademarks of Cybermation International Distribution SRL. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation. IBM, AIX, OS/2, OS/400, RS/6000, z/OS, and WebSphere are trademarks of IBM. Sun, Solaris, and Java are trademarks of Sun Microsystems, Inc. SPARC is a trademark or registered trademark of SPARC International, Inc. Intel and Pentium are registered trademarks of Intel Corporation. Linux is a registered trademark of Linus Torvalds. HP-UX and ALLBASE are registered trademarks of Hewlett Packard. Oracle Applications and Oracle E-Business Suite are the trademarks or registered trademarks of Oracle. Oracle is a registered trademark of Oracle Corporation. PeopleSoft is a trademark of PeopleSoft Inc. UNIX is a registered trademark of the Open Group. WebLogic and WebLogic Server are trademarks of BEA Systems, Inc. SAP, R/3, and ABAP are trademarks or registered trademarks of SAP AG. Micro Focus and Net Express are registered trademarks of Micro Focus International Limited. All other brand and product names are trademarks, registered trademarks or service marks of their respective companies. Contents
Using this guide ...... 1 Other guides in the Cybermation ESP: dSeries library ...... 2 1 Introduction to Cybermation ESP: dSeries 5 Cybermation ESP system components ...... 6 How the components work together ...... 7 2 Maintaining Cybermation ESP Desktop Client 9 About the ESP Desktop Client Admin perspective...... 10 Using the Admin perspective...... 10 Managing server connections ...... 11 Changing passwords...... 11 Resetting a user’s password...... 12 Viewing a list of users connected to the server ...... 12 Applying software updates to ESP Desktop Client ...... 13 3 Working with Cybermation ESP Server 15 Checking server status ...... 16 About ESP Server start types ...... 17 Starting the server ...... 18 Stopping the server...... 20 Recycling the server...... 20 Configuring the server...... 22 Changing the email addresses or SMTP server ...... 23 Setting up failure notifications when Applications fail to generate...... 24
ESPD-5.0-AG-01 iii Setting up notifications when a job is forced to complete...... 25 Checking the server memory usage...... 25 Viewing a list of artifacts in the system...... 26 Viewing your license status...... 26 Monitoring the shared directory...... 27 Changing the Windows service name for Cybermation ESP Server...... 30 Installing the ESP High Security Option...... 30 4 Working with Cybermation ESP Agents 33 Supported ESP Agents and related documentation...... 34 Setting up ESP Agents to work with ESP Server...... 34 Setting up strong encryption between ESP System Agents and ESP Server...... 51 Removing ESP Agent from ESP Server ...... 54 Modifying ESP Agent configuration parameters...... 55 Configuring the z/OS ESP Agent...... 57 Controlling ESP Agents ...... 58 5 Establishing and Controlling Security 61 About ESP Server security...... 62 Working with users ...... 66 Working with groups ...... 69 Summary of security permissions ...... 72 Setting up your ESP Server security network...... 84 6 Handling Cybermation ESP Server Log Files 95 About log files...... 96 Changing a log’s location or name ...... 97 Creating an audit log report ...... 98 Filtering messages sent to trace logs...... 99 Summary of filter IDs ...... 101 7 Administering ESP High Availability 105 ESP High Availability terminology...... 106 The ESP High Availability process ...... 107 Configuring ESP High Availability detection...... 110 Changing the type of failback...... 112 Switching Primary and Standby roles ...... 112 Converting to an ESP High Availability installation...... 113 Verifying the ESP High Availability configuration ...... 118 Preventing auto connection to the Standby ...... 120 8 Monitoring SNMP Messages 121 About SNMP messages ...... 122 Interpreting SNMP messages ...... 122 Changing the SNMP Manager settings ...... 124 Using third-party SNMP Managers ...... 125
iv ESPD-5.0-AG-01 Contents
Enabling SNMP messages from ESP System Agents ...... 125 Receiving SNMP messages...... 126 Stopping the SNMP trap receiver...... 126 Working with the SNMP Message Viewer ...... 127 9 Working with the Packaged Oracle Database 129 About the packaged Oracle database ...... 130 Changing the database connectivity properties ...... 131 Implementing a disaster recovery solution...... 132 Changing to a new database ...... 141 Changing the database name...... 142 10 Cybermation ESP: dSeries Maintenance Procedures 145 Setting up a housekeeping Application...... 146 Packaged Oracle database maintenance ...... 148 ESP Server maintenance...... 154 ESP Agent maintenance ...... 161 11 Command Console Commands 167 Command definitions and syntax...... 168 Issuing appcmd commands using the Command Utility ...... 171 12 Integrating Cybermation ESP: dSeries Servers 175 Integrating your ESP Servers...... 176 Verifying your integration...... 180 A Oracle Administration Primer 183 Oracle 10g for ESP Server overview ...... 184 Oracle server directory structure...... 185 Oracle network components ...... 186 Database initialization files...... 189 Oracle database instances (SID) ...... 190 Database objects...... 193 Data backup and restore...... 194 Troubleshooting...... 196 Common administrative commands...... 196 Useful queries...... 199 B Using the Import/Export Utility 201
Index 205
ESPD-5.0-AG-01 v vi ESPD-5.0-AG-01 Using this guide
This guide assumes you have installed Cybermation ESP: dSeries. Use this guide for post-installation tasks such as setting up security, configuring ESP High Availability, and performing maintenance tasks. Following installation, you will need to perform the following administrative tasks.
Administrator Task See Define, configure, maintain, and control • Working with Cybermation ESP Agents Agents • ESP Agent maintenance Create and maintain security profiles • Establishing and Controlling Security Set up, maintain, and periodically archive • Handling Cybermation ESP Server Log and clear server logs produced within Files Espresso • Performing an automated cleanup of ESP Server • Archiving server log files • Clearing server log files Backup, diagnose, and maintain the Espresso • Working with the Packaged Oracle relational database Database
ESPD-5.0-AG-01 1 Section–Other guides in the Cybermation ESP: dSeries library
Other guides in the Cybermation ESP: dSeries library
Installing Cybermation ESP: dSeries This guide covers the installation process for installing and configuring ESP Server’s components: the relational database, ESP Server and its default Agent, and ESP Desktop Client. The guide provides instructions for two types of installation: single ESP Server (stand-alone) installations and ESP High Availability installations.
Cybermation ESP System Agent Administrator’s Guide This guide describes how to install, configure, secure, maintain, and control ESP System Agent. This guide also provides instructions to configure Cybermation Hosts to work with ESP System Agent. The final chapters contain troubleshooting and reference information.
Getting Started with Cybermation ESP: dSeries This guide is for new Cybermation ESP: dSeries users who want to learn about the product. Getting Started is a tutorial that teaches users how to schedule and run jobs with Cybermation ESP: dSeries.
User’s Guide The User’s Guide describes how to define, schedule, monitor, and control workflow with Cybermation ESP: dSeries. This guide is the primary resource for schedulers and operators. It includes information on forecast and history reporting, previously found in the Workload Reporting Guide, and real-life examples from the Examples Cookbook.
Beyond Basic Scheduling: A Guide to Using Scripts This guide is intended for anyone who wants to create scripts that work with Applications. The first six chapters of the guide cover JavaScript scripts. The final chapter and appendix cover the ESPmgr utility and using it within scripts.
Receiving email notifications from Cybermation You can register to receive email notifications when new releases, new fixes, or new documents are available on the Cybermation Support website. 1. Go to the Cybermation Support site located at http://support.cybermation.com. 2. Log in. Note: You can register as a Support site user on the Login page.
2 ESPD-5.0-AG-01 3. On the Home page, select Notification Sign-up. 4. For each Cybermation product you are using, select the events you want to receive notification for: • New Releases • New Fixes • New Documentation 5. Click Submit. Note: You can cancel email notifications at any time by repeating the above steps and deselecting your options.
ESPD-5.0-AG-01 3 Section–Other guides in the Cybermation ESP: dSeries library
4 ESPD-5.0-AG-01 Introduction to Cybermation ESP: dSeries
Cybermation ESP: dSeries provides distributed job scheduling and workflow management across the enterprise. It is a simple, flexible, and powerful solution for enterprise application integration (EAI) and systems operations. Platform- independent as a result of its next-generation XML and JAVA architecture, Cybermation ESP: dSeries functions across various server and Enterprise Resource Planning (ERP) platforms, including •UNIX • Compaq NSK • Windows NT/2000/2003 • SAP® R/3 •z/OS® • PeopleSoft • IBM OS/400 • Oracle • OpenVMS
ESPD-5.0-AG-01 5 Section–Cybermation ESP system components
Cybermation ESP system components
A Cybermation ESP system consists of the following components: • Cybermation ESP Server • Cybermation ESP Desktop Client • Cybermation ESP Agents
Cybermation ESP Server Cybermation ESP Server is the core of the Cybermation ESP system. ESP Server handles and directs all incoming communication from ESP Desktop Client, ESP Agents, a Relational Database Management System (RDBMS), and a peer ESP Server in an ESP High Availability configuration. ESP Server requires a RDBMS for message processing, ESP High Availability, and storing server configuration files, resource definition files, and historical reporting data. ESP Server is packaged with an Oracle database you can choose to install. You can also configure ESP Server to work with other databases.
Cybermation ESP Desktop Client Cybermation ESP Desktop Client is a graphical interface for defining, monitoring, and controlling enterprise workflow. The interface enables users to quickly drag-and- drop their way through workflow definitions, manage calendars, and monitor and control batch workflow, regardless of the operating system. A Cybermation ESP system can have many ESP Desktop Clients. ESP Desktop Client also includes the administrator’s tools for setting up, monitoring, and diagnosing problems with the ESP: dSeries solution. For example, administrators can use the SNMP Message Viewer to monitor traps sent from ESP Servers, ESP Agents or jobs.
6 ESPD-5.0-AG-01 Chapter 1–Introduction to Cybermation ESP: dSeries
Cybermation ESP Agents Cybermation ESP Agents are applications that extend batch workflow across multiple operating systems. ESP Agents automatically run batch workflow and monitor its progress. ESP Agents communicate with ESP Server through TCP/IP. When you install ESP Server, a default ESP System Agent automatically installs on the same platform as ESP Server. For example, if you install ESP Server on Windows 2000, an ESP System Agent automatically installs on the same machine.
How the components work together
The following diagram illustrates how the Cybermation ESP components work together. • The top of the diagram shows ESP Client, the application you use to schedule and monitor workflow and manage the Cybermation ESP system. • The middle of the diagram shows ESP Server, which services requests from ESP Desktop Client and submits work to ESP Agent machines. ESP Server runs on UNIX and Windows platforms. • The bottom of the diagram shows ESP Agents, which initiate and monitor the scheduled workflow (such as commands and scripts) and communicate status information to ESP Server.
ESPD-5.0-AG-01 7 Section–How the components work together
8 ESPD-5.0-AG-01 Maintaining Cybermation ESP Desktop Client
This chapter contains the following topics: • About the ESP Desktop Client Admin perspective • Using the Admin perspective • Managing server connections • Changing passwords • Resetting a user’s password • Viewing a list of users connected to the server • Applying software updates to ESP Desktop Client
ESPD-5.0-AG-01 9 Section–About the ESP Desktop Client Admin perspective
About the ESP Desktop Client Admin perspective
As an administrator, you will use the ESP Desktop Client Admin perspective to perform tasks associated with ESP Server and ESP Agents. The Admin perspective provides access to the following views: • Command Console — For issuing appcmds • Console View — For monitoring messages sent from ESP Server • Security — For setting up and managing users and groups to access ESP Server • SNMP Message Viewer — For monitoring SNMP messages that contain information regarding ESP Server, ESP Agents, ESP High Availability, and Alerts • Topology — For configuring ESP Server parameters, setting ESP High Availability parameters, defining ESP Agents in the ESP Server topology, and configuring ESP Agent parameters
Using the Admin perspective
To use the ESP Desktop Client Admin perspective, you must connect to ESP Server as a user assigned ADMINGRP permissions. The default administrator’s user ID and password are ADMIN and admin. Typically, ESP Desktop Client is set up with a default server connection that uses the SCHEDMASTER user ID. For convenience, you may want to either change your default connection to use ADMIN or add a server connection for ADMIN. Note: For security purposes, you should change the ADMIN user’s password once you have connected.
10 ESPD-5.0-AG-01 Chapter 2–Maintaining Cybermation ESP Desktop Client
Managing server connections
You can add, modify and remove ESP Desktop Client server connections.
To add a server connection 1. Collect the following information for ESP Server: • Address — The IP address or DNS name of the machine where you have installed ESP Server • Port — The ESP Server client port number. The default value is 7500. • User ID — Your Cybermation ESP user name for scheduling. The default name is SCHEDMASTER (in upper case). • Password — The password that corresponds to the user ID. The default scheduling password is schedmaster (in lower case). 2. Open the ESP Desktop Client Connections view using one of the following methods: • Click the Show the Connections View icon.
• Select Window > Show View > Connections. 3. Click the Create a new connection icon.
The New Connection dialog appears. 4. Enter the required details and click Save.
To delete a server connection In the ESP Desktop Client Connections view, right-click the server connection and select Remove.
Changing passwords
Passwords don’t expire. Users can change their passwords any time. When specifying a new password, do not leave the field blank. The password cannot exceed 32 characters. The first character must be alphabetical. The password is case sensitive.
ESPD-5.0-AG-01 11 Section–Resetting a user’s password
To change a password 1. Connect to ESP Server using ESP Desktop Client. 2. In the Connections view, right-click the server connection and select Change Password. 3. In the Change Password dialog, enter the old and new passwords, confirm the new password, and click OK.
Resetting a user’s password
From time to time, users may forget their passwords. You can reset a user’s password using the Admin perspective Security view.
To reset a password 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Right-click Security and select Open. 4. On the Users tab, right-click the user whose password you need to reset and select Reset Password. 5. In the Reset Password dialog, enter the new password, confirm it, and click OK.
Viewing a list of users connected to the server
You can use an appcmd to see who is connected to ESP Server. The generated list is helpful if, for example, you need to shut down the server and want to notify those users who are connected before shutting it down.
To view a list of users connected to ESP Server 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the about command. The command lists ESP Desktop Client users connected to ESP Server.
12 ESPD-5.0-AG-01 Chapter 2–Maintaining Cybermation ESP Desktop Client
Related topic For more information about appcmds, see “Command definitions and syntax” on page 168.
Applying software updates to ESP Desktop Client
To provide required software updates for ESP Desktop Client, Cybermation may occasionally release fixes. You can download these fixes and distribute them internally to your ESP Desktop Client users.
Distributing the software updates 1. Download the update zip file: a. Go to the Cybermation Support website at http://support.cybermation.com. b. Log in. c. Select Product Entitlement. d. From the list of companies, select your company and click Refresh. e. Select the product and version. f. Under Fixes, download the available files. 2. Create a directory on your system where users will access the updates. 3. Copy the update zip file to the directory you set up in step 2. 4. Notify users that updates are available and where to find them. Tip: You might send users an email that specifies the name and location of the update zip file. Your communication might also include the instructions described under “Installing an ESP Desktop Client update”.
Related topic To know when updates are available, you can request email notifications from Cybermation. For details, see “Receiving email notifications from Cybermation” on page 2.
Installing an ESP Desktop Client update 1. Open ESP Desktop Client. 2. Select Help > Software Updates. The Select Update Archive dialog appears. 3. Browse to the location where the updates are stored.
ESPD-5.0-AG-01 13 Section–Applying software updates to ESP Desktop Client
4. Select the update zip file, and click Open. The Updates dialog appears. 5. In the tree view, select the update feature and click Next. Tip: To view a description of the feature, click More Info. 6. Follow the instructions on screen. 7. After you complete the installation, restart ESP Desktop Client.
14 ESPD-5.0-AG-01 Working with Cybermation ESP Server
This chapter contains the following topics: • Checking server status • About ESP Server start types • Starting the server • Stopping the server • Recycling the server • Configuring the server • Changing the email addresses or SMTP server • Setting up failure notifications when Applications fail to generate • Checking the server memory usage • Viewing a list of artifacts in the system • Viewing your license status • Monitoring the shared directory • Changing the Windows service name for Cybermation ESP Server • Installing the ESP High Security Option
ESPD-5.0-AG-01 15 Section–Checking server status
For information about Cybermation ESP Server maintenance, see Chapter 10, “Cybermation ESP: dSeries Maintenance Procedures”
Checking server status
Checking ESP Server status on UNIX 1. Change to the ESP Server installation directory. 2. Run the status script. ./status If the server is active, the script displays the process id of ESP Server, for example ::::::::::::::: ESP Server ::::::::::::::: 18982 If the server is inactive, the process id is blank.
Checking ESP Server status on Windows You can check the server status using Windows services, if the server is installed as a service, or using Windows Console Mode.
To check ESP Server status using Windows services 1. From the Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. For the Cybermation ESP: dSeries Server service, check the Status field. • If ESP Server is active, the field displays Started. • If ESP Server is inactive, the field is blank.
To check ESP Server status using Windows Console Mode If ESP Server is running in console mode, you can check its window (Start Cybermation ESP: dSeries Server) for information on its status. In console mode, ESP Server stops running if the Start Cybermation ESP: dSeries Server window is closed.
16 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
About ESP Server start types
The start type specifies whether ESP Server will start with a warm or cold start. The following table describes the impact of a warm and cold start on active workflow, Events, and resource status.
Impact on Cold Start Warm Start Active workflow Deletes any active workflow and Reads active workflow from the associated states time ESP Server shuts down. Upon startup, ESP Server continues running workflow from this point onward. Events Does not process Events that Reads and schedules Events that have not been processed at the have not yet been processed at the time of shutdown time of shutdown and continues monitoring for Events that are to be processed Resource status Reverts the status of all logical Reads the status of all logical resources to their original resources from the time of definition shutdown and continues managing resource states from this point onward
Performing a cold start By default, ESP Server starts with a warm start. When you perform a cold start, ESP Server deletes all active workflow and associated states, and you lose all active processing data. For rare situations when you must perform a cold start, use the following procedures. Note: If the runonce.properties files exists in the ESP Server directory, ESP Server will use the start type specified in the file. Otherwise, ESP Server uses a warm start.
Stand-alone configuration
To perform a cold start on a single ESP Server 1. Stop ESP Server. 2. Open the runonce.properties.bak file, located in the ESP Server installation directory. 3. Ensure the start type in the file is set to cold. 4. Remove the .bak extension from the filename to change it to runonce.properties.
ESPD-5.0-AG-01 17 Section–Starting the server
5. Start ESP Server. When ESP Server starts, it will rename the runonce.properties file to runonce.properties.bak and default to a warm start.
Cybermation ESP High Availability configuration
To perform a cold start on a single ESP Server in a Cybermation ESP High Availability configuration 1. Stop both servers. Note: If either server is left running, the cold start cannot take effect. 2. Open the runonce.properties.bak file, located in the ESP Server installation directory. 3. Ensure the start type in the file is set to cold. 4. Remove the .bak extension from the filename to change it to runonce.properties. 5. Start the server you want to cold start. When ESP Server starts, it will rename the runonce.properties file to runonce.properties.bak and default to a warm start. 6. Start the other server.
Starting the server
Starting ESP Server on UNIX 1. Change to the ESP Server installation directory. 2. Run the startEspServer script. ./startEspServer ESP Server starts. If this server is a standalone server, or the preferred server in an ESP High Availability configuration, the default ESP Agent also starts. Note: The startup script does not start the packaged Oracle database. You must start the Oracle database using another script. To start the packaged Oracle database, see “Starting an Oracle instance” on page 196.
Starting ESP Server on Windows You can start ESP Server using Windows services or using shortcuts.
18 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
To start ESP Server as a Windows service 1. From the Windows Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. Right-click the Cybermation ESP: dSeries Server service, and click Start. Note: The ESP Server installation program provides the option of selecting an automatic startup type for the Windows service. The default startup type for the service is manual. If you left the default and want the service to start automatically at startup, change its startup type to Automatic.
Important: In an ESP High Availability configuration, to start ESP Server as a Windows service, the Cybermation ESP: dSeries Server service needs to log on to a user account with network privileges. For more information, see “Changing the user account a Windows service logs on to” on page 19.
To start ESP Server using Windows shortcuts If you did not install ESP Server as a Windows service, do one of the following: • Select Start > Programs > Cybermation > ESP dSeries Server > Start ESP Server. • In Windows Explorer, go to the ESP Server installation directory and double-click startServer.exe. The Start ESP Server window appears. ESP Server runs in console mode. Note: Keep this window open. Closing the window stops ESP Server.
Changing the user account a Windows service logs on to
Note: This procedure applies to ESP High Availability configurations only. 1. From the Services dialog, right-click the Cybermation ESP: dSeries Server service, and click Properties. 2. On the Log On tab, change the Log on as account to an account with network privileges. You can now start Cybermation ESP: dSeries Server as a Windows service.
ESPD-5.0-AG-01 19 Section–Stopping the server
Stopping the server
Stopping ESP Server on UNIX 1. Change to the ESP Server installation directory. 2. Run the stopEspServer script. ./stopEspServer ESP Server stops. If this server is the standalone server, or the preferred server in an ESP High Availability configuration, the default ESP Agent also stops. Note: The stop script does not stop the packaged Oracle database. You must stop the Oracle database using another script. To stop the packaged Oracle database, see “Stopping an Oracle instance” on page 197.
Stopping ESP Server on Windows You can stop ESP Server using Windows services, if the server is installed as a service, or using shortcuts.
To stop ESP Server using Windows services 1. From the Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. Right-click the Cybermation ESP: dSeries Server service, and click Stop.
To stop ESP Server using Windows shortcuts If you did not install ESP Server as a Windows service, do one of the following: • Select Start > Programs > Cybermation > ESP dSeries Server > Stop ESP Server. • In Windows Explorer, go to the ESP Server installation directory and double-click stopServer.exe.
Recycling the server
To recycle ESP Server, you must stop it and then restart it. You can stop ESP Server through the Command Console or from the machine where the server is installed. However, you cannot restart ESP Server from the Command Console. To restart the server, you must start it from the machine where it is installed.
20 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
Note: Recycling ESP Server does not start or stop the default ESP Agent. To stop and start the ESP Agent, refer to “Controlling ESP Agents” on page 58.
Stopping ESP Server using the Command Console 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: stop On the server machine, ESP Server returns an acknowledgement message indicating that it has shut down. ESP Server with pid (19287) is down
Note: • To use the stop command, you must be logged in as a user who is a member of the ADMIN group. • If ESP Server does not respond with an acknowledgment message, you must stop it using the stopServer script.
Stopping ESP Server on UNIX 1. Change to the ESP Server installation directory. 2. Run the stopServer script. ./stopServer ESP Server stops. If the default Agent is running, the script does not stop it.
Stopping ESP Server on Windows See “Stopping ESP Server on Windows” on page 20.
Restarting ESP Server on UNIX You must restart ESP Server from the machine where it is installed. You cannot restart the server using the Command Console. 1. Change to the ESP Server installation directory. 2. Run the startServer script. ./startServer The script starts ESP Server.
ESPD-5.0-AG-01 21 Section–Configuring the server
Restarting ESP Server on Windows See “Starting ESP Server on Windows” on page 18.
Configuring the server
ESP Server has two sets of configuration parameters you can change: instance parameters and shared parameters. Instance parameters contain server- and system- specific information, such as ports and server names. Shared parameters contain non- server-specific information, such as the information shared between ESP Servers in an ESP High Availability installation. You can view and modify server parameters using the Admin perspective Topology view. Note: For changes to take effect, you must recycle ESP Server.
Configuring server parameters 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select a menu option: • Configure instance parameters • Configure shared parameters 5. Configure the parameters. 6. Click Update to save your changes. 7. If you are modifying any of the following parameters, you must recycle ESP Server:
Topology View Properties Server Shared Parameters > • Global Agent heartbeat interval in minutes General tab • Messages processed before garbage collection • Maximum client sessions • Disk space monitoring ESP Agent
22 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
Topology View Properties Server Shared Parameters > • Enable Automatic Failback to Preferred Server Failover tab •Ping Frequency Server Shared Parameters > • SNMP Manager Address SNMP tab •SNMP Input Port • Community of SNMP Manager Server Instance Parameters > •ESP Server RMI Port Properties •ESP Desktop Client Port •Preferred server
Changing ESP Server port numbers 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select Configure instance parameters. 5. Modify the port settings. • ESP Server RMI Port — The port ESP Desktop Client uses to make RMI calls to ESP Server. The default port number is 1099. • ESP Desktop Client Port — The port ESP Server uses to communicate with ESP Desktop Client. The default is 7500. 6. Click Update to save your changes. 7. Recycle ESP Server.
Changing the email addresses or SMTP server
You can specify two email addresses for ESP Server communications: • Email address to identify ESP Server is the address to identify email sent by a particular ESP Server. • Send administrative emails to is a valid internal email address to which ESP Server will send license-related and other administrative issues. Use this procedure to change these email addresses or the name of your SMTP server.
ESPD-5.0-AG-01 23 Section–Setting up failure notifications when Applications fail to generate
To change the email addresses 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select Configure shared parameters. The Server shared parameters view appears. 5. Click the Email tab. 6. Change the fields, as required. 7. Click Update to save your changes.
Setting up failure notifications when Applications fail to generate
By default, ESP Server sends an email when a triggered Event fails or fails to generate an Application. An SNMP message appears in the email subject and contains a short description of the failure reason. You can also set up SNMP failure notification for these situations. ESP Server sends the email notification to the ESP Server email recipient defined during ESP Server installation. You can change the recipient after installation by setting the Send administrative emails To parameter. To prevent ESP Server from sending email when an Application fails to generate, set Send email message when Application trigger fails to false.
To set up failure notifications when Applications fail to generate 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select Configure shared parameters. The Server shared parameters view appears. 5. On the General tab, set the following fields to true, as required: • Send email message when application trigger fails • Send SNMP message when application trigger fails 6. Click Update to save your changes.
24 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
Setting up notifications when a job is forced to complete
Explanation of what this does and when you would set this up.
To set up notifications when a job is forced to complete 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select Configure shared parameters. The Server shared parameters view appears. 5. On the General tab, set the Process notifications when a WOB is forced to complete value to true. 6. Click Update to save your changes.
Checking the server memory usage
You can check the ESP Server current memory using the Command Console. The console displays the total free memory and maximum heap size.
To check ESP Server memory usage 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: memcheck The Command Console displays a message similar to the example below.
ESPD-5.0-AG-01 25 Section–Viewing a list of artifacts in the system
Viewing a list of artifacts in the system
You can view the total number of each ESP artifact types in your system using the Command Console. The console lists the following ESP artifact types: • Agents • Forecasts •Alerts •Groups • Applications • JavaScripts • Calendars • Resources • Events •Users
To view a list of artifacts in the system 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: countlist The Command Console displays a message similar to the example below.
Viewing your license status
You can issue a command to view the total number of licenses available, the number of licenses in use, and the temporary license’s expiry date.
To view your license status 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console.
26 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
4. Enter the following command: licensestatus The details of your license appear.
Monitoring the shared directory
ESP Server has two built-in monitoring features for its shared directory. You will receive warning notifications when the following situations occur: • The disk space drops below a warning threshold • Access to the NFS server used by the shared directory becomes slow or unavailable Note: To monitor the disk space, you must set the disk monitoring ESP Agent.
Related topics • “Monitoring disk space available for the shared directory” on page 27 • “Setting the disk monitoring ESP Agent” on page 27 • “Configuring the disk space monitor” on page 28 • “Monitoring the shared directory availability” on page 29 • “Setting the warning threshold for monitoring the shared directory availability” on page 29
Monitoring disk space available for the shared directory ESP Server stores PSE Pro Object Database files in a shared directory. Over time, the disk space for storing those files decreases. To prevent that disk space from running out, ESP Server has a built-in feature that uses the default ESP Agent to monitor disk space. When the disk space drops below a warning threshold, ESP Server will send an SNMP message and an email to the administrative email recipient designated in its topology. When the disk space drops below a shutdown threshold, ESP Server shuts itself down. Note: If you use ESP High Availability, when disk space becomes critically low, ESP Server shuts down the Standby before shutting itself down.
Important: Do not run ESP Server from an account that uses disk quotas; disk space monitor does not monitor disk quotas.
Setting the disk monitoring ESP Agent
To enable disk space monitoring, you must set the Disk monitoring ESP Agent parameter in the ESP Server topology to the name of your default Agent.
ESPD-5.0-AG-01 27 Section–Monitoring the shared directory
To set the disk monitoring ESP Agent 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select Configure shared parameters. The Server shared parameters view appears. 5. In the Disk monitoring ESP Agent field, enter the name of the ESP Agent you will use to monitor disk space. 6. Click Update to save your change. 7. Recycle ESP Server.
Configuring the disk space monitor Cybermation recommends you leave the default settings for disk space monitoring. However, if required, you can override the defaults by adding the following properties to the espresso.properties file located in the ESP Server installation directory.
Property Default Description value diskmon.freekbwarnthresh 102400 The warning threshold value in kilobytes. When the free disk-space level drops below this value, ESP Server will send an email and SNMP message. By default, ESP Server starts warning when the disk space drops below 100 MB. diskmon.freekbshutdownthres 5120 The warning shutdown value in kilobytes. When the free disk space level drops below this value, ESP Server shuts down. By default, ESP Server shuts down when the disk space drops below 5 MB. diskmon.cancelwarndeltakb 1024 After ESP Server issues the disk-space warning, it cancels the warning when the disk-space level reaches the sum of this property and the diskmon.freekbwarnthresh value. diskmon.rewarnintervalmin 15 The minimum interval, in minutes, at which ESP Server re-sends warning messages when disk space is low. For example, if you set this property to 5, ESP Server re-sends warning messages at least five minutes apart. diskmon.emailprefix If set, ESP Server will prefix the subject line of the warning email with this property’s value. Use this field if you automatically filter subject lines.
28 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
Monitoring the shared directory availability If the NFS server where the shared directory resides becomes unavailable, ESP Server stops processing workflow. When the NFS server becomes available, ESP Server will continue processing workflow normally. No workflow is lost during the unavailable period. To test access to the shared directory, ESP Server performs a check of the time it takes to write and delete an 8K file to and from the shared directory. If the time to write and delete the file exceeds a threshold value, ESP Server sends an SNMP message and email warning that access to the shared directory is slow. If ESP Server can’t write the file, it sends an SNMP message and email warning that the shared directory is unresponsive. In this case, the NFS server may be down.
Setting the warning threshold for monitoring the shared directory availability If you are receiving too many warning messages, you can increase the time set by the Max. acceptable disk write time parameter. The default threshold value is 1000ms.
To set the warning threshold 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the network tree, right-click the ESP Server connection and select Configure shared parameters. The Server shared parameters view appears. 5. In the Max. acceptable disk write time field, enter the time (in milliseconds). 6. Click Update to save your change. 7. Recycle ESP Server.
ESPD-5.0-AG-01 29 Section–Changing the Windows service name for Cybermation ESP Server
Changing the Windows service name for Cybermation ESP Server
When you install ESP Server on Windows, you must install it as a Windows service. If you want to change the service name after installing ESP Server, you can by following this procedure.
To change the Windows service name for ESP Server 1. Run the removeServices.bat script located in the
Installing the ESP High Security Option
Stand-alone configuration
To install the ESP High Security Option on a single ESP Server 1. Stop ESP Server. 2. Copy the strongencryption.jar file into the following ESP Server directory:
30 ESPD-5.0-AG-01 Chapter 3–Working with Cybermation ESP Server
3. Edit the following variables. • On UNIX: Edit the classpath variable in
ESP High Availability configuration
To install the ESP High Security Option in an ESP High Availability configuration 1. Install the ESP High Security Option on the Standby. Follow the instructions above for the stand-alone configuration. When you have completed this step, the Standby should be running. 2. Using the ESP Desktop Client Admin perspective, open the Command Console and invoke the changerole command against either the Primary or Standby. 3. Install the ESP High Security Option on the Primary. Follow the instructions above for the stand-alone configuration. When you have completed this step, the Primary should be running. 4. Using the ESP Desktop Client Admin perspective, open the Command Console and invoke the changerole command against either the Primary or Standby.
Related topics “Setting up strong encryption between ESP System Agents and ESP Server” on page 51.
ESPD-5.0-AG-01 31 Section–Installing the ESP High Security Option
32 ESPD-5.0-AG-01 Working with Cybermation ESP Agents
This chapter contains the following topics: • Supported ESP Agents and related documentation • Setting up ESP Agents to work with ESP Server • Setting up strong encryption between ESP System Agents and ESP Server • Removing ESP Agent from ESP Server • Modifying ESP Agent configuration parameters • Defining ESP Agent users • Configuring the z/OS ESP Agent • Controlling ESP Agents For information about ESP Agent maintenance, see Chapter 10, “Cybermation ESP: dSeries Maintenance Procedures.”.
ESPD-5.0-AG-01 33 Section–Supported ESP Agents and related documentation
Supported ESP Agents and related documentation
Cybermation ESP: dSeries supports the following types of ESP Agents: • ESP System Agent (for UNIX and Windows) • ESP Agent for z/OS • ESP Business Agent for PeopleSoft • ESP Business Agent for SAP Solutions • ESP Business Agent for Oracle E-Business Suite • ESP Business Agent for Micro Focus Enterprise Server
Related documentation For detailed information for a specific ESP Agent, refer to its associated documentation. The following documents are supplied for each ESP Agent: • Release Notes • Administrator’s Guide To schedule and monitor workflow on different operating system using ESP Agents, refer to the Cybermation ESP: dSeries User’s Guide.
Setting up ESP Agents to work with ESP Server
You can install ESP Agents on various operating systems to run workflow using ESP Server. You can also configure virtual ESP Agents. A virtual ESP Agent is one that runs with a Tandem or OpenVMS parent ESP Agent. The parent ESP Agent routes requests to the virtual ESP Agent. To set up an ESP Agent to work with ESP Server, complete the following steps.
Step Activity Page 9 1. Prepare to install ESP Agent 35 2. Install and configure ESP Agent. 35 3. Add ESP Agent to the ESP Server Topology. 35 4. Set up ESP Agent security on ESP Server. 37
34 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Step Activity Page 9 5. Start ESP Agent. 46 6. Check the communication between ESP Agent and ESP Server. 47 7. Run a test Application to verify your setup. 47
Prepare to install ESP Agent Before you install ESP Agent, complete these steps: • Verify the system requirements To ensure your system meets the requirements, refer to the Release Notes for the specific ESP Agent you are installing. • Collect the information you need to install ESP Agent Refer to the Administrator’s Guide for the information you must collect.
Install and configure ESP Agent For installation and configuration instructions, refer to the Administrator’s Guide provided with each ESP Agent. Note: Ensure you have enough licenses available before adding a new ESP Agent to the ESP Server topology. To check your license status, see “Viewing your license status” on page 26.
Add ESP Agent to the ESP Server Topology 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click the ESP Server connection and select Add Agent. The New Agent view appears. 5. In the Agent type field, select the type of ESP Agent you want to add. The Properties tab appears. 6. Complete the following mandatory fields: • Name — agentname parameter from the ESP Agent’s agentparm.txt file.
ESPD-5.0-AG-01 35 Section–Setting up ESP Agents to work with ESP Server
Note: ESP Server converts the ESP Agent name into uppercase. Ensure the agentname parameter in the agentparm.txt file is in uppercase; otherwise, ESP Server and ESP Agent cannot communicate. • Address — IP address or DNS name of the machine where ESP Agent is installed. • Port number — IP port number ESP Agent uses to listen for traffic. This port number must match the communication.inputport field in the agentparm.txt file. • Release number — Release number for ESP Agent. • Encryption key — security.cryptkey parameter from the agentparm.txt file, minus the prefix 0x. • Heartbeat frequency (in minutes) — Frequency with which you want ESP Server to send the heartbeat signal. If you want individual ESP Agents to have their own heartbeat frequencies, set the shared configuration parameter Global Agent heartbeat frequency to zero. • Heartbeat attempts before sending an SNMP notification — Number of heartbeat signals the ESP Server attempts before it sends an SNMP message indicating ESP Agent inactivity. 7. Enter values for the other fields, as required. 8. To add a virtual ESP Agent to a Tandem or OpenVMS parent ESP Agent, complete the following steps: a. Click the Virtual ESP Agent tab. b. Enter the parameter values for the virtual ESP Agent. 9. If an ESP Agent user specified in a job definition requires a password, define ESP Agent users. a. Click the Users tab. b. Click Add. The Add ESP Agent User dialog appears. c. Complete the required fields: User ID, Password, and Confirm Password. 10. Click Update.
Set up security To set up security, complete the following steps.
Step Activity Page 9 1. Set up ESP Agent security on ESP Server. 37 2. Set up 56-bit encryption on ESP Server. 37 3. Set up encryption on ESP Agent. 38
36 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Step Activity Page 9 4. Turn on ESP Agent security. 38 5. Set up local security on ESP Agent. 39 6. Reload the ESP Agent security file. 45
Set up ESP Agent security on ESP Server To control ESP Agent access, you must set up the following security permissions on ESP Server.
Access to Requires Allow Access to this Type of Access permission ESP Agents AGENT.agentname Run work on the ESP Agent specified by agentname User IDs AGENTUSR.agentname.user Run a job on the ESP Agent id specified by agentname under the user ID specified by userid Issue AGENTMSG.cmd.agentname Issue ESP Agent control commands commands to the ESP Agent specified by agentname. Note: cmd is APPCMD.
Related topics “Set up local security on ESP Agent” on page 39
Set up 56-bit encryption on ESP Server You must set up regular 56-bit encryption on ESP Server by specifying the encryption key for your ESP Agent in the ESP Server Topology. If you are eligible, you can also set up strong (256-bit) encryption.
To set up 56-bit encryption on ESP Server 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click ESP Agent and select View Properties. 5. In the Encryption key field, enter the encryption key for ESP Agent. This is the same key specified in the security.cryptkey parameter in the agentparm.txt file, but without the prefix “0x”. 6. Click Update.
ESPD-5.0-AG-01 37 Section–Setting up ESP Agents to work with ESP Server
Related topics “Setting up strong encryption between ESP System Agents and ESP Server” on page 51
Set up encryption on ESP Agent To set up encryption on ESP Agent, add the security.cryptkey parameter to the agentparm.txt file located in the ESP Agent installation directory. The value for the security.cryptkey parameter on ESP Agent must match the encryption key defined for ESP Agent on ESP Server. If these values do not match, encryption will fail and communication will not be allowed between ESP Server and ESP Agent. Tip: To locate the encryption key, use the Admin perspective to open the Topology view for the Agent.
Syntax security.cryptkey=
Example security.cryptkey=0x0102030405060708 The security.cryptkey parameter turns on encryption and automatically turns on Level 2 message prefixing, which is required for encryption. Level 2 message prefixing is required in all instances. If security.cryptkey is set, ESP Agent uses Level 2 message prefixing regardless of the value specified in the communication.prefixlevel parameter.
Turn on ESP Agent security 1. In the agentparm.txt file located in the ESP Agent installation directory, change the value of the security.level parameter to on. security.level=on 2. Stop and restart ESP Agent.
38 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Related topics “Modifying ESP Agent configuration parameters” on page 55
Set up local security on ESP Agent
Important: In this section, examples apply to UNIX operating systems. Paths contain forward slashes, no drive is identified, and references are made to root authority. Apart from these items, however, the examples apply to ESP Agent on Windows also.
About the security file The ESP Agent security file is named security.txt. It must reside in the ESP Agent installation directory. If the file does not exist, default security rules apply, as described under “Default security rules” on page 40. The security file contains three types of rules: • Rules that allow or prevent ESP Server users from submitting jobs that run under a specific user ID, from a specific directory. These rules begin with the letter x, as follows: x
Rule parameter descriptions The following describes the rule parameters.
Entry Description rule type Identifies the ESP Agent rule type (x) identifies a rule controlling execution of scripts and commands. (c) identifies a rule controlling operational commands to an ESP Agent. (f) identifies FTP commands.
ESPD-5.0-AG-01 39 Section–Setting up ESP Agents to work with ESP Server
Entry Description (Continued) permission Identifies whether access is allowed or denied. This parameter contains two possible values: • a indicates permission is allowed. • d indicates permission is denied. ESP_HostuserID Identifies the ESP Host Manager name or the ESP Host user ID this rule applies to Agent_UserID Identifies the user ID on the ESP Agent machine under which the job is run FTP_UserID Identifies the FTP user ID this rule applies to path Identifies the path ESP Host is allowed to submit jobs from, using the user ID identified by Agent_UserID operation Identifies the FTP command. Valid commands are • list — Changes directory and list files (CD, LIST, NLST) • read — Retrieves the file (RETR) • write — Stores the file or makes a directory (STOR, STOU, RNFR, RNTO, MKD) • delete — Deletes the file or directory (DELE, RMD) Note: The above commands apply to ESP Agent as FTP server. For FTP jobs, only read and write apply. command Identifies the control command. Valid commands are: shutdown, refresh, clrfiles, flush, quiesce, and restart. You can also specify an asterisk (*) for all commands.
Default security rules When ESP Agent starts, it checks for the security file. • If the file does not exist, default security rules apply. • If the file exists, ESP Agent uses the rules defined in the file. It does not use the default security rules. If a request does not have a match in the security file, ESP Agent denies the request. • If the file does not exist and ESP Agent security is turned off in the agentparm.txt file (security.level=off), ESP Agent does not check security. Note: The following default security rules apply when the security file does not exist, and ESP Agent security is turned on in the agentparm.txt file (security.level=on):
xa** + x d * root + ca** * fa** + Note: For ESP Agent on Windows, substitute Administrator for root.
40 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Security rule for Micro Focus jobs If ESP Agent security is turned on (security.level=on), you must add the following security rule to the security.txt file in order to run Micro Focus jobs on the ESP Agent machine. This rule allows any ESP Server user to submit Micro Focus jobs that run under any ESP Agent user ID.
x a * * cybMFCommand.exe If you do not want to allow all ESP Server users to submit MicroFocus jobs, you can restrict the submission of Micro Focus jobs to specific users instead. For example, the following rule allows the ESP Server user, SCHEDMASTER, to submit Micro Focus jobs that run under the ESP Agent user ID, SYSTEM.
x a SCHEDMASTER SYSTEM cybMFCommand.exe If you do not add the Micro Focus security rule to the security.txt file and ESP Agent security is turned on, ESP Agent will not run Micro Focus jobs.
Additional security file rules
Wildcards The Cybermation Host name, user IDs, paths, verbs, and subverbs can contain a single wildcard character at the end of the field only. For wildcards, use the asterisk (*) and the plus sign (+).
Wildcard Description Asterisk (*) Represents 0 or more character matches in the current directory only plus sign (+) Represents 0 or more character matches in the current directory and all subdirectories
Start point and spacing Every security rule starts in column 1. Items on a line are • Separated by one or more blanks or tab characters. • End with a new-line character.
Comment lines The file can contain comment lines. An asterisk (*) or a number sign (#) in column 1 identifies comment lines.
ESPD-5.0-AG-01 41 Section–Setting up ESP Agents to work with ESP Server
Understanding security rule interpretation For a rule to match, three components of a rule have to match. If two or more rules match, the closest match overrides the others, as follows: Interpretation Explanation A specific rule overrides a generic rule. A generic rule /u1/jsmith is a rule that contains wildcards. overrides /u1/jsmith* If both rules are generic, the more specific one /u1/jsmith/scripts/* overrides the other. overrides /u1/jsmith* /u1/jsmith/scripts/a* overrides /u1/jsmith/scripts* The ESP_HostuserID user ID takes precedence over A rule is considered a closer match if the server user ID, and the server user ID takes the ESP_HostuserID is a closer precedence over the directory name. match. If the ESP_HostuserIDs of two rules are the same, the rule with the closest matching server ID overrides the other. If there is still ambiguity after these rules have been c d root * * applied, a deny rule will override an allow rule. overrides c a root * *
Security file example #1
Line Security File Example #1 1# Example 1 2 * Last updated on August 01, 2002. 3 xa * * + 4 x d * gem* + 5 x a * root /prod/employee+ 6 x d * root /prod/employee* 7 x a * root /prod/+ 8 x d * root /prod/expense 9 x a * root /prod/* 10 x d * root /prod/+ 11 c a * CONTROL * Note: You must specify both types of permissions (x and c) even if there is no change to one of the entry types.
Line Explanation of Security File Example #1 1 Comment line
42 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Line Explanation of Security File Example #1 (Continued) 2 Comment line 3 Allows the ESP Server user to submit jobs under any user ID, from all directories 4 Prohibits the ESP Server user from submitting jobs under gem, or any user IDs that begin with gem, from all directories 5 Allows the ESP Server user to submit the following jobs as root Job Example A job called employee from /prod/employee directory /prod/ All jobs beginning with employee /prod/employee_pay from directory /prod/ /prod/employee_vacation All jobs from the subdirectory /prod/employee/fulltime_pay /prod/employee/ or its /prod/employee/sales/ subdirectories fulltime_pay All jobs from directories whose name /prod/employee1999/ begins with employee in directory fulltime-pay /prod/ or their subdirectories /prod/employee1999/sales/ fulltime_pay 6 Prohibits the ESP Host user from submitting any jobs called employee, or any jobs that begin with employee, as root in directory /prod/ 7 Allows the ESP Host user to submit all jobs as root from directory /prod/ and onwards 8 Prohibits the ESP Host user from submitting the job expense as root from /prod/ 9 Allows the ESP Host user to submit all jobs as root in directory /prod/ 10 Denies the ESP Host user from submitting any jobs as root from directory /prod/ and onwards 11 Allows all users to issue all control commands to this ESP Agent
Security file example #2
Line Example 1 # Example 2 2 * Last updated on February 28, 2002. 3 x a SCHED* root /prod/+ 4 x a ADM* root* /prod/* 5 x a JSMITH * /prod/+ 6 c a MANAGER CONTROL * 7 fa * * + 8 f d user1 write /prod/* 9 f a user1 write /prod/W*
ESPD-5.0-AG-01 43 Section–Setting up ESP Agents to work with ESP Server
Line Example (Continued) 10 f d l* read /prod/report* 11 f a user2 * /program files/ cyb+
Line Explanation of Security File Example #2 1Comment line 2Comment line 3 Allows any ESP Host user ID beginning with SCHED to submit jobs as root from the directory /prod/ and onwards 4 Allows any ESP Host user ID beginning with ADM to submit jobs as root, or under any user ID beginning with root, in directory /prod/ 5 Allows JSMITH to submit jobs under any user ID from directory /prod/ and onwards 6 Allows MANAGER to issue all control commands to this Agent 7 Allows all users to submit any FTP jobs in any directory 8Denies user1 writing to any file in the directory /prod/ 9 Allows user1 to write to any file starting with W in directory /prod 10 Denies all users whose ID starts with the letter l read access to any file that begins with report in the directory /prod/ 11 Allows user2 from using all FTP operations in any directory starting with /program_files/cyb and any subdirectories
How the security file works 1. A sample security.txt file contains these entries.
c a * * * x d * * + x a SCHEDMASTER UNIXUSR1 /usr/+ This file allows Cybermation ESP: dSeries user SCHEDMASTER to submit jobs under user UNIXUSR1 from directory /usr/ and its subdirectories. 2. Security is turned on in the agentparm.txt file: security.level=on 3. The job definition includes the user ID under which the job is to be run (UNIXUSR1 in the sample above), as shown in the following job definition examples:
44 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Cybermation ESP: dSeries job definition
Reload the ESP Agent security file The refresh command reloads an ESP Agent’s security file.
To reload ESP Agent’s security file 1. Connect to the ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: agentmsg control agentname(agentname) refresh agentname is the name of the ESP Agent whose security file you want to reload. The command reloads the ESP Agent’s security file.
ESPD-5.0-AG-01 45 Section–Setting up ESP Agents to work with ESP Server
Start ESP Agent
Starting ESP Agent on UNIX 1. Change to the directory ESP Agent is installed in. 2. Enter the following command: ./cybAgent & The ESP Agent runs in the background. Note: Before you start ESP Agent, make sure the cybAgent process and related Java processes from the previous run of ESP Agent were shut down correctly.
Starting ESP Agent on Windows using the Start Agent program shortcut
Click the Start Agent program shortcut.
Starting ESP Agent on Windows from the Control Panel
1. Open the Windows Control Panel. 2. Double-click Administrative Tools. 3. Double-click Services. 4. Right-click the ESP Agent service and click Start. The default name for ESP Agent is ESP System Agent for Microsoft Windows.
Starting ESP Agent on Windows from the command prompt 1. Change to the directory ESP Agent is installed in. By default, ESP Agent is installed in C:\Program Files\Cybermation\ESP System Agent 2. Enter one of the following: • cybAgent -a • net start Service_Name
Starting ESP Agent on Windows automatically By default, the service is installed as Manual Startup Type. It is not started on system startup. You can start ESP Agent manually via the Control Panel or command prompt. You can set the Service Startup Type as Automatic, and the service will start at startup. 1. Open the Windows Control Panel. 2. Double-click Administrative Tools.
46 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
3. Double-click Services. 4. Right-click the ESP Agent service and select Properties. The default name for ESP Agent is ESP System Agent for Microsoft Windows. 5. At Startup type on the Properties dialog, select Automatic.
Check the communication between ESP Agent and ESP Server If you have administrator access to ESP Server, you can verify communications between ESP Agent and ESP Server by checking the afmlog.txt file. 1. After defining ESP Agent to ESP Server, start ESP Agent. 2. Wait for a minute to ensure that communication between ESP Server and ESP Agent is established. 3. Open the afmlog.txt file located in
Run a test Application to verify your setup This section describes the steps to create a test Application to verify ESP Agent works with Cybermation ESP: dSeries. In this verification test, you create an Application that contains one job. Note: Before you run the following procedures, ensure ESP Server, the relational database server, and ESP Agent are running.
ESPD-5.0-AG-01 47 Section–Setting up ESP Agents to work with ESP Server
Step 1: Define your workflow
Connecting to ESP Server using ESP Desktop Client 1. Launch ESP Desktop Client. 2. In the Connect to ESP dialog, enter a user ID and password, and click Connect. The welcome screen appears. Tip: If your ESP Server is not the default connection name, select the connection name, and enter the appropriate user ID and password for the ESP Server.
Creating an Application 1. From the welcome screen, click the Define icon. The Define perspective opens. Ensure Application Workspace is the active view. 2. In the Application Workspace view, right-click your ESP Server name and click New. The Application Properties dialog appears. 3. In the Name field, enter Quick and click OK. The Event Triggers and Workflow Objects palettes appear in an Application view labelled Quick. Note: You can resize and move the views to suit your requirements.
Defining an Event Trigger in the Application You define an Event to schedule the workflow. When an Event is triggered, the Application runs. Setup: Ensure the tab containing the Application name Quick is active. 1. From the Event Triggers palette, click Trigger. 2. Click the workspace to the right of the palette. A Trigger job icon appears on the workspace. 3. Right-click the Trigger icon and click Edit. The New Date/Time Event view appears. 4. In the Prefix field, enter a prefix that identifies the Event you want to create. An Event name has two parts: a prefix and a descriptive name. The prefix allows you to group Events together. For example, a prefix could be the name of a user ID or group ID. You can list Events based on their prefix. 5. In the Name field, enter a name for the Event. Event names must be unique. You can give your Event a name related to the function the Event is performing. For this scenario, enter Quick.
48 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
6. In the Application to run field, enter Quick. 7. In the Specify schedule criteria section, click the Add Row button. 8. In the Statement field, enter Run. 9. In the Criteria field, enter 4 pm daily. 10. Click Upload to upload the Event definition to ESP Server. A message appears informing you when this Event will first execute.
Defining a job in the Application For this test Application, create a script or batch file on the ESP Agent machine for the test job: 1. Using Notepad or another text editor, create a file. 2. In the file, type exit. 3. Save the file as test.bat (Windows) or test.sh (UNIX). Remember where you stored the test file. You can verify communication between ESP Agent and ESP Server using a job type (for example, UNIX and Windows jobs) that can run the test file you created. Setup: Ensure the tab containing the Application name Quick is active. 1. From the Workflow Objects job palette, click the job type that matches your ESP Agent machine. For example, choose the UNIX job type if your ESP Agent is installed on a UNIX machine. 2. Click the workspace to the right of the job palette. A job icon appears on the workspace. 3. Right-click the job icon and click Edit. The job definition dialog appears. 4. In the Name field, enter a name for the job or use the default. 5. In the Agent name field, enter or select the ESP Agent name. 6. In the Command to run field, enter the full path to the test file you created. 7. Click OK.
Uploading the Application to ESP Server In the Application Workspace view, right-click the Quick Application and click Upload. The Application is uploaded to ESP Server.
ESPD-5.0-AG-01 49 Section–Setting up ESP Agents to work with ESP Server
Simulating the Event Use the simulation feature to see a graphical representation of the test Application for the Event Trigger schedule criteria. 1. Right-click the Trigger icon and click Simulate. The Simulate the Event dialog appears. 2. Leave the fields blank and click OK. Both a graphical representation and a text-based representation of the Application appear.
Step 2: Run your workflow The Application runs according to the criteria you define in the Event Trigger. However, you can also trigger the Event manually to run immediately.
Triggering the Event manually 1. Click the >> icon and click Event Manager. The Event Manager view appears. 2. In the Event Manager view, click the plus (+) sign beside Connections. 3. Double-click your ESP Server name. The Events view for your ESP Server appears. 4. In the Prefix field, enter the prefix the test Application is grouped under, and click List. A list of the events under the specified prefix appears. 5. Right-click the test Application name Quick and click Trigger. The Trigger the Event dialog appears. 6. Leave now in the Schedule criteria field (because you will trigger the Event immediately) and select Submit Application on hold. 7. Click OK.
Step 3: Monitor your workflow
Viewing the Application 1. Click the >> icon and click Monitor. The Application View view appears. 2. In Application View, click the plus (+) sign beside ESP Servers. 3. Right-click your ESP Server name and click Subscribe Active. A plus (+) sign appears beside the ESP Server name.
50 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
4. Click the plus (+) sign beside the ESP Server name. All active Applications that you have access to appears. 5. Click the plus (+) sign beside the test Application name Quick. The QUICK folder expands, and a folder for each Application generation appears. 6. Double-click the test Application generation. A graphical view of the test Application appears.
Monitoring the Application Monitor the jobs in the graphical view. One by one the jobs start and end, and status information is updated. Some of the jobs may go into a WAITING state because they have built-in time delays. You should see all jobs in a COMPLETE state within a few minutes. Once the final job goes into a COMPLETE state, your setup is successful. As jobs in an Application pass through different states, the job label indicates the job’s state and the border surrounding the job icon changes color. • Jobs with a blue border are in a COMPLETE state. • Jobs with a green border are in an EXEC state (the job is running). • Jobs with a red border are in a TROUBLE state. If the job label indicates AGENTDOWN, it means that ESP Agent is not running or that Cybermation ESP: dSeries cannot contact ESP Agent. Ensure the Topology entries for ESP Agent match what you specified during installation. If you set up Strong Encryption for this Agent, ensure the encryption key is the same on ESP Agent and Cybermation ESP: dSeries. If a job goes into a SUBERROR state, it usually means the path to the command file is wrong.
Setting up strong encryption between ESP System Agents and ESP Server
You can set up strong (256-bit) encryption between ESP System Agents and ESP Server. Support for strong encryption is only available with Release 7 ESP System Agents.
Important: The high security option for ESP Server and ESP System Agent is subject to export controls. To determine whether you are eligible for this option, contact Cybermation.
ESPD-5.0-AG-01 51 Section–Setting up strong encryption between ESP System Agents and ESP Server
To set up strong encryption between ESP Agents and ESP Server, complete the following steps.
Step Activity Page 9 1. Set up strong encryption on ESP Agent. 52 2. Enable strong encryption for ESP Agent in the ESP Server 53 topology. 3. Restart ESP Agent. 53 4. Test the encryption between ESP Server and ESP Agent. 54
Note: You must install the ESP Server High Security Option.
Set up strong encryption on ESP Agent After you install the standard edition of ESP System Agent R7, you run the strongEncrypt executable file you obtain from Cybermation.
To set up strong encryption on ESP Agent 1. Obtain the strongEncrypt executable file for ESP System Agent R7 from Cybermation. 2. Stop ESP Agent if it is running. 3. Run the strongEncrypt executable file: • On UNIX: At the command prompt, type ./strongEncrypt.bin -i console
• On Windows, double-click the strongEncrypt.exe file. Note: The installation program prompts you for the path to ESP Agent. Make note of the path. You use this path in step 4. 4. Use a command prompt and change to the ESP Agent installation directory. 5. Run the CybKeygen utility that the strongEncrypt file installed. • On UNIX: Type CybKeygen.sh 0xkey strong • On Windows: Type cybkeygen.bat 0xkey strong where key is the strong encryption key. This key must be 16 to 64 characters long. You can specify up to 64 alphanumeric characters, using any digit and letters A through F only.
52 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Note: Make note of your new encryption key. You need this key when you enable strong encryption of ESP Agent in the ESP Server topology. Running the CybKeygen utility does the following: • Converts the encryption key defined in the agentparm.txt file (security.cryptkey parameter) and creates cryptkey.txt. • Sets the value of the security.cryptkey parameter in the agentparm.txt file to the path of the cryptkey.txt. • Installs a utility called CybKeygen.
Enable strong encryption for ESP Agent in the ESP Server topology You use the ESP Desktop Client Admin perspective to configure ESP Agent. The key you specified for ESP Agent using the CybKeygen utility and the key you specify using the ESP Server topology must be the same. If the keys are different, ESP Server and ESP Agent cannot communicate and you receive an AGENTDOWN state when you try to run workflow.
To enable strong encryption for ESP Agent in the ESP Server topology 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click ESP Agent and select View Properties. 5. Change the value of these parameters: • Encryption Key — Enter the encryption key you created for ESP Agent using the CybKeygen utility. Do not enter the "0x" used as the prefix when you changed the key using the CybKeygen utility. • Strong Encryption Enabled — Select true. 6. To accept the changes, click Update.
Restart ESP Agent After you have set up strong encryption on ESP Agent and enabled strong encryption in the ESP Server topology, restart ESP Agent.
To restart ESP Agent 1. On the ESP Agent machine, change to the ESP Agent installation directory. 2. At the command prompt, enter the following command to stop ESP Agent: •On UNIX ./cybAgent -s • On Windows cybAgent -s
ESPD-5.0-AG-01 53 Section–Removing ESP Agent from ESP Server
3. Enter the following command to start ESP Agent: •On UNIX ./cybAgent & • On Windows cybAgent -a
Test the encryption between ESP Server and ESP Agent You can run and monitor a simple Application, like the VERIFY Application packaged with ESP Server, to test the communication between ESP Server and ESP Agent. Note: If you use the VERIFY Application, make sure you change the ESP Agent name to the ESP Agent you are testing.
Troubleshooting
When there is a communication problem between ESP Server and ESP Agent, the AGENTDOWN state appears for the jobs in the Monitor perspective. The following are possible causes: • ESP Agent is not started. • ESP Server and ESP Agent have different encryption keys. • The parameters in ESP Server’s Topology are different than the ones defined in the agentparm.txt file. Make sure the values of parameters listed in the table below are the same.
Topology agentparm.txt Value Name agentname Parent communication.managerid Address communication.manageraddress Port communication.inputport number
Removing ESP Agent from ESP Server
1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view.
54 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
4. In the Topology view, right-click the ESP Agent you want to remove and select Remove Agent. The ESP Agent disappears from the Topology view. Note: If you remove a parent ESP Agent that contains virtual ESP Agents, the parent and all its virtual ESP Agents are removed. Also, if you remove all the virtual ESP Agents from a parent ESP Agent, that parent is also removed.
Modifying ESP Agent configuration parameters
1. Connect to ESP Server using ESP Desktop Client.
2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click the ESP Agent whose properties you want to modify and select View Properties. 5. Change the parameter values, as required. For parameter descriptions, select the field and press F1. 6. To save your changes, the save icon at the top right corner of the Agent view. Note: For the changes to take effect, you must recycle (stop and restart) ESP Agent.
Changing the log level on ESP Agent Dependency: ESP System Agent Release 7 You can change the log level on a remote ESP System Agent without restarting it. Log levels specify the type of information to record in the ESP Agent log files, which help in troubleshooting ESP Agent problems. 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: agentmsg control agentname(agentname) loglevel(2|3|4|5) persistent(TRUE|FALSE) agentname is the name of the ESP Agent whose log level you want to change. Example agentmsg control agentname(WINAGENT) loglevel(5) persistent(TRUE)
ESPD-5.0-AG-01 55 Section–Modifying ESP Agent configuration parameters
Log levels ESP Agent supports log levels 0, 1, 2, 3, 4, and 5, where level 0 provides the least information and level 5 provides the most. • Levels 0, 1, and 2 create logs of any errors including the receiver and transmitter logs. • Level 3 adds queues. • Levels 4 and 5 add debugging information. Level 2 is adequate for general, initial testing, and level 0 is adequate for production unless problems arise requiring more details for troubleshooting. For more information on the log files created for each log level, see the troubleshooting chapter in the Cybermation ESP System Agent Administrator’s Guide.
Changing the log level permanently The persistent operand enables you to change the log level permanently. • If the change is not permanent (the persistent operand is set to FALSE), the log level is changed for the current session only. The log level is reset to the level defined in the agentparm.txt file the next time ESP Agent is restarted. • If the change is permanent (the persistent operand is set to TRUE), the log.level parameter in the agentparm.txt file is updated with the new log level. A backup copy of the original agentparm.txt file is created with the name agentparm.txt.manager.
Defining ESP Agent users If an ESP Agent user specified in a job definition requires a password, such as Windows, SAP, PeopleSoft, FTP, and database users do, you must define the user to ESP Server. This procedure does not apply to UNIX and Oracle users.
To define an ESP Agent user 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click ESP Agent you want to add the user to and select View Properties. The ESP Agent view appears. 5. Click the Users tab. 6. Click Add. The Add Agent User dialog appears.
56 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
7. Complete the required fields: User ID, Password, and Confirm Password. 8. Click Update.
Changing an ESP Agent user’s password
To change an ESP Agent user’s password 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click ESP Agent you want to change a user’s password for and select View Properties. 5. Click the Users tab. 6. Select the user and click Change Password. The Change password dialog appears. 7. Complete the required fields and save.
Configuring the z/OS ESP Agent
To use the z/OS ESP Agent, you need to specify the encryption key the z/OS ESP Agent uses to communicate with ESP Server. Note: In an ESP High Availability configuration, the z/OS ESP Agent requires PTF SU02174 to run z/OS workflow.
To configure the z/OS ESP Agent’s encryption key in the ESP Server topology 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the Topology view, right-click the z/OS ESP Agent you want to configure and select View Properties. 5. In the Encryption key field, enter the encryption key that is defined for the COMMCHAN initialization parameter in the z/OS ESP Agent's Agent definition data set. Note: All z/OS ESP Agents must use the same encryption key to communicate with ESP Server.
ESPD-5.0-AG-01 57 Section–Controlling ESP Agents
Related procedures • To add the z/OS ESP Agent to the ESP Server network topology, see “Add ESP Agent to the ESP Server Topology” on page 35. • For information on configuring an ESP Agent definition data set, see the ESP System Agent IBM z/OS Installation and Configuration Guide.
Controlling ESP Agents
Use ESP Agent control commands to control ESP Agents from a client machine. Enter the following ESP Agent commands from the Command Console.
Command Description Syntax shutdown Shuts down the Agent after all workload agentmsg control has completed agentname(agentname) shutdown refresh Reloads the Agent security file agentmsg control agentname(agentname) refresh clrfiles Clears the Agent log files agentmsg control agentname(agentname) clrfiles flush Purges all pending messages for the agent agentname(agentname) flush specified Agent quiesce Holds all messages to be sent to the agent agentname(agentname) named Agent. To resume message quiesce sending, use the restart command. restart Resumes sending messages to the named agent agentname(agentname) Agent. Used following quiesce. restart
Shutting down an ESP Agent You can shut down an ESP Agent currently processing workflow using the shutdown command. ESP Agent will shut down and all workflow will continue running. However, ESP Agent cannot track the workflow states.
To shut down an ESP Agent 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: agentmsg control agentname(agentname) shutdown agentname is the name of the ESP Agent you want to shut down.
58 ESPD-5.0-AG-01 Chapter 4–Working with Cybermation ESP Agents
Clearing ESP Agent receiver messages ESP Agent receiver messages are messages sent to an ESP Agent to tell it what workflow needs to be processed. These messages are queued to await processing. By issuing the flush command, you can clear these pending messages. 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: agent agentname(agentname) flush agentname is the name of the ESP Agent whose messages you want to clear. This command clears all workload processing messages in the queue.
Holding ESP Agent receiver messages The quiesce command holds all ESP Agent receiver messages in the queue until you enter the restart command. 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: agent agentname(agentname) quiesce agentname is the name of the ESP Agent whose receiver messages you want to hold. The command holds all ESP Agent receiver messages in the queue until you enter the restart command.
Resuming message sending to an ESP Agent The restart command resumes sending messages the quiesce command previously held. 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console.
ESPD-5.0-AG-01 59 Section–Controlling ESP Agents
4. Enter the following command: agent agentname(agentname) restart agentname is the name of the ESP Agent whose messages you want to resume sending. The command releases all messages the quiesce command previously held.
60 ESPD-5.0-AG-01 Establishing and Controlling Security
This chapter contains the following topics: • About ESP Server security • Working with users • Working with groups • Summary of security permissions • Setting up your ESP Server security network
ESPD-5.0-AG-01 61 Section–About ESP Server security
About ESP Server security
ESP Server security is maintained through a set of security profiles. A security profile can represent a user or a group (a collection of users). Security profiles have permissions associated with them. For example, they determine access levels to Applications and ESP Server topology information.
Users You define users with a user ID and password. You then grant them certain permissions that determine their access within ESP Server.
Predefined users When you first install ESP Server, the installation program creates two predefined users: ADMIN and SCHEDMASTER. You must use these users to connect to ESP Server to perform post-installation tasks. When you create new users, these predefined users serve as models for security permissions.
ADMIN user The ADMIN user contains the required permissions for administering ESP Server and is associated with the ADMINGRP group. The ADMIN’s default password is admin.
SCHEDMASTER user The SCHEDMASTER user contains the required permissions for scheduling workflow and is associated with the SCHEDGRP group. The SCHEDMASTER’s default password is schedmaster.
Related topics • “Creating a user” on page 66 • “Creating a group” on page 69
Groups You use groups to define the same set of permissions for different users. Once you assign permissions to a group, you can then associate users with that group. All users in a particular group share the permissions that belong to that group. Groups are useful for users who share common duties and activities.
62 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Predefined groups When you first install ESP Server, it creates the following predefined groups: • ADMINGRP • EVERYONE •OPERGRP • SCHEDGRP Use these groups as models for other groups that you create.
ADMINGRP The ADMINGRP group contains the required permissions for administering ESP Server. Users associated with this group can • View, add, and modify topology information • View, add, and modify security profiles • View, add, modify, lock, and unlock resource definitions • Use a resource in an Application • Add, change, and delete job definitions in the VERIFY Application • Lock and unlock the VERIFY Application • Download, display, and modify the VERIFY Application • Run the VERIFY Application • Issue commands against jobs in the VERIFY Application • Insert jobs into the VERIFY Application • Display and update the VERIFY Event • Issue commands against the VERIFY Event The ADMIN user belongs to this group.
EVERYONE Every user automatically belongs to the EVERYONE group. Users associated with this group can • Read the SYSTEM calendar • Use terms defined in the SYSTEM calendar
ESPD-5.0-AG-01 63 Section–About ESP Server security
OPERGRP The OPERGRP group contains permissions needed by operators to do their work. Users associated with this group can • Display any Alert definition. • Download and display any Application. • Run any Application. • Issue commands against jobs in all Applications. • Insert jobs into any Application. • Display any Event. • Issue commands against all Events.
SCHEDGRP The SCHEDGRP contains permissions needed by schedulers to do their work. Users associated with this group can • View, add, delete, lock, unlock, and modify • Any Alert definition • Any Application • Any Calendar • Any resource definition • Any Event • Add, modify, and delete any job definitions in any Application • Run work on any ESP Agent • Issue ESP Agent control commands to any ESP Agent • Use any user ID on any ESP Agent • Reference any calendar in an Event • Use an Application during run time The SCHEDMASTER user belongs to this group.
Related topics • “Creating a group” on page 69 • “Adding, changing or removing group permissions” on page 69
Permissions Permissions determine what type of access a user or group has to a particular element of ESP Server. You can also use permissions to restrict access to specific things. For example, you can restrict access to a specific Application.
64 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Permissions can contain two types of access: • Alter, Update, or Read access • Allow or Deny access With Allow or Deny access, you can use Deny to create exceptions to a user or group’s normal access. For example, if a user needs to have access to all Calendars except the PAYCAL Calendar, you can give the user Allow access to CALENDAR.*, but create a permission with a Deny access called CALENDAR.PAYCAL. You add permissions to users and groups to define their security access. You can add permissions to a user or group when you first create them, or you can add them later.
User vs. group permissions Sometimes a user belonging to group can contain permissions that contradict the group permissions. For example, a user with Allow access to AGENT.A1UNIX may belong to a group with a Deny permission for AGENT.A1UNIX. Also, in the case of permissions with Alter, Update, and Read access, a user may have a higher access level than the group. For example, a user may have Alter access to ADMIN.Security Files and belong to a group with Read access to ADMIN.Security Files. In these cases, the user permission always overrides the group permission. The user in the group with a Deny permission for AGENT.A1UNIX has Allow access to that ESP Agent, and the user who belongs to the group with Read access to ADMIN.Security Files has Alter access.
Conventions for permissions Permissions follow a standard convention in this guide: permission.value (accesslevel) • permission is the name of the permission. • value defines what the permission affects. In the Security view, you select value from a dropdown menu when you add a permission to a user or group. You can use an asterisk(*) in the value field of most permissions to indicate that the value affects all aspects of the permission. • accesslevel defines the type of security access this permission allows. Depending on the type of permission, you can specify the following: • Alter, Update, or Read • Allow or Deny
ESPD-5.0-AG-01 65 Section–Working with users
Working with users
Creating a user When you first create a user, you can add permissions to it, or add it to groups as you create it, or you can modify the user’s details later.
To create a user 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Click the Add new user icon. 5. On the New User tab, complete the following fields: • User ID — The user’s user ID. Each user ID must be unique. The first character must be alphabetic, and the user ID cannot exceed 20 characters. User IDs convert to uppercase as you type them. • User Name — An optional user’s name • Password — The user’s password. The first character must be alphabetic, and the password cannot exceed 32 characters. Passwords are case-sensitive and must be different than the user ID. • Confirm Password —Enter the password again. 6. To add the user to a group, select a group under Available Groups and click Add. 7. To assign the user permissions, do the following: a. Click the Permission tab. b. Click Add. The Add Permissions dialog appears. c. In the Permission type field, select the permission you want to add. d. In the Value column, type the permission’s value. To specify multiple values, use a wildcard (*). For example, Application name set to PAYROLL* matches all Applications that begin with PAYROLL. e. In the Access section, select the access level for the permission. For Alter, Update, and Read, selecting the highest level of access also selects the levels below. For example, Alter access grants alter, update, and read access. f. Click OK. The permission is added to the user. Repeat the previous step until you have added all the permissions the user needs. 8. To add the user, click Update.
66 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Adding, changing or removing user permissions 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Right-click the user you want to change permissions for and select View Details. 5. Click the Permissions tab. 6. To add a permission, do the following: a. Click Add. b. In the Permission type field, select the permission you want to add. c. In the Value column, type the permission’s value. To specify multiple values, use a wildcard (*). For example, Application name set to PAYROLL* matches all Applications that begin with PAYROLL. d. In the Access section, select the access level for the permission. For Alter, Update, and Read, selecting the highest level of access also selects the levels below. For example, Alter access grants alter, update, and read access. e. Click OK. 7. To change a permission, do the following: a. Select the permission you want to change. b. Click Edit. c. In the Edit permission dialog, make the required changes and click OK. 8. To remove a permission, do the following: a. Select the permission you want to remove. b. Click Remove. c. Click Yes. 9. When finished, click Update.
Adding a user to a group 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Right-click the user you want to change permissions for and select View Details. 5. On the Groups tab, select the group and click Add. • To select multiple groups, press the Shift key while you select. • To copy a group list from an existing user, use the Copy group list from user field. 6. Click Update.
ESPD-5.0-AG-01 67 Section–Working with users
Removing a user from a group 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Right-click the user you want to change and select View Details. 5. On the Groups tab, in the Connected Groups list, select the groups you want to remove and click Remove. 6. Click Update.
Changing a user’s name 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Right-click the user you want to change and select View Details. 5. In the User Name field, enter the name and click Update.
Removing a user from the ESP Server topology 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Right-click the user you want to remove and select Remove User. 5. Click Yes. Note: Removing a user does not remove any groups associated with it.
Related topics • “Users” on page 62 • “Groups” on page 62 • “Summary of security permissions” on page 72 • “Resetting a user’s password” on page 12
68 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Working with groups
Creating a group 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Click the Group tab. 5. Click Add new group. 6. On the New Group tab, complete the following fields: • Name — Mandatory group name. Each group must have a unique name. A group name must start with an alphabetic character and cannot exceed 20 characters. • Description — Brief description of the group. The first character must be alphabetic. The description cannot exceed 40 characters. 7. To add users to the group, select a user under Available Users and click Add. Tip: To copy a user list from an existing group, use the Copy user list from group field. 8. To assign the group permissions, do the following: a. Click the Permission tab. b. Click Add. c. On the Add Permissions tab, in the Permission type field, select the permission you want to add. d. In the Value column, type the permission’s value. To specify multiple values, use a wildcard (*). For example, Application name set to PAYROLL* matches all Applications that begin with PAYROLL. e. In the Access section, select the access level for the permission. For Alter, Update, and Read, selecting the highest level of access also selects the levels below. For example, Alter access grants alter, update, and read access. f. Click OK. The permission is added to the group. Repeat the previous step until you have added all the permissions the user needs. Tip: To copy a permissions list from an existing group, use the Copy permission list from group field. 9. To add the group, click Update.
Adding, changing or removing group permissions 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective.
ESPD-5.0-AG-01 69 Section–Working with groups
3. Open the Security view. 4. Click the Groups tab. 5. To add a permission, do the following: a. Right-click the group and select View Details. b. Click the Permissions tab. c. Click Add. d. In the Permission type field, select the permission you want to add. e. In the Value column, type the permission’s value. To specify multiple values, use a wildcard (*). For example, Application name set to PAYROLL* matches all Applications that begin with PAYROLL. f. In the Access section, select the access level for the permission. For Alter, Update, and Read, selecting the highest level of access also selects the levels below. For example, Alter access grants alter, update, and read access. g. Click OK. 6. To change a permission, do the following: a. Right-click the group and select View Details. b. Click the Permissions tab. c. Select the permission you want to change. d. Click Edit. e. In the Edit permission dialog, make the required changes and click OK. 7. To remove a permission, do the following: a. Right-click the group you want to remove and select Remove Group. b. Click Yes. 8. When finished, click Update.
Changing a group’s description 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Security view. 4. Click the Groups tab. 5. Right-click the group you want to change and select View Details. 6. Make the required changes, and click Update.
Removing a group from the ESP Server topology
To remove a group from the ESP Server topology 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective.
70 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
3. Open the Security view. 4. Right-click the group you want to remove and select Remove Group. 5. Click Yes. Note: Removing a group does not remove the users associated with it.
Related topics • “Users” on page 62 • “Groups” on page 62 • “Summary of security permissions” on page 72
ESPD-5.0-AG-01 71 Section–Summary of security permissions
Summary of security permissions
The following table summarizes the permissions you can add to users and groups.
Permission Determines access to Access Values See Page ADMIN Network topology and security files Alter, Update, Read 72 AGENT Running workflow on an ESP Agent Allow, Deny 73 AGENTMSG ESP Agent control commands Allow, Deny 74 AGENTUSER ESP Agent user IDs Allow, Deny 75 ALERT Alert definitions Alter, Update, Read 76 APPL Application definitions Alter, Update, Read 76 APPLX Active Applications Allow, Deny 78 CALENDAR Calendars Alter, Update, Read 79 CMD Issuing commands from the Allow, Deny 80 Command Console EVENT Events Alter, Update, Read 81 EVENTX Issuing commands against an Event Allow, Deny 82 JAVASCRIPT JavaScript scripts Alter, Update, Read 83 RESOURCE Resources Alter, Update, Read 83
ADMIN Affects topology information and security files.
Syntax ADMIN.Network Topology Determines access to the topology. This permission affects what a user can do in the Topology view. Tasks include • Modifying ESP Server configuration and initialization parameters • Modifying ESP Agent configuration parameters • Adding and removing ESP Agents from your network You can associate the following access values with this permission: • Alter enables a user or group to view, update, add, and delete topology information. • Update enables a user or group to view and update topology information. • Read enables a user to view topology information. Note: To access the Topology view, a user requires Update or Alter access.
72 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Examples: ADMIN.Network topology
Permission Definition ADMIN.Network Topology The user can view and modify ESP Server and ESP Agent (Alter) parameters as well as add and delete ESP Agents from the network. ADMIN.Network Topology The user can view and modify ESP Server and ESP Agent (Update) parameters in the Topology view. ADMIN.Network Topology The user can view topology information. (Read)
Syntax ADMIN.Security Files Determines access to ESP Server security files. You can associate the following access values with this permission: • Alter enables a user or group to view, update, add, and delete users and groups. • Update enables a user or group to view and update users and groups. • Read enables a user or group to view user and group information. Note: To access the Security Profiles Manager, a user requires Update or Alter access.
Examples: ADMIN.Security Files
Permission Definition ADMIN.Security Files (Alter) • The user can view and modify users, groups, and permissions. • The user can add users and groups and can create new permissions. ADMIN.Security Files (Update) The user can view and modify users, groups, and permissions. ADMIN.Security Files (Read) The user can view user and group information.
AGENT Determines whether a user or group can or cannot run work on an ESP Agent.
Syntax AGENT.agentname where agentname is the name of an ESP Agent in the topology. Use an asterisk in its place to specify that all ESP Agents are affected by this permission. For example, the permission AGENT.Unix1 determines whether a user or group can or cannot run work on the ESP Agent named UNIX1. The permission AGENT.*
ESPD-5.0-AG-01 73 Section–Summary of security permissions
determines whether a user or group can or cannot run work on all ESP Agents in the topology. You can associate the following access values with this permission: • Allow enables a user or group to run work on the ESP Agent specified in agentname. • Deny restricts a user or group from running work on the ESP Agent specified in agentname.
Examples: AGENT usage
Permission Definition AGENT.A1* (Allow) The user can run work on any ESP Agent whose name begins with A1. AGENT.A1UNIX (Deny) The user cannot run work on the ESP Agent named A1UNIX.
AGENTMSG Determines whether a user or group can or cannot issue ESP Agent control commands to an ESP Agent using the Command Console.
Syntax AGENTMSG.CONTROL.agentname where • CONTROL indicates that this permission affects ESP Agent control commands • agentname is the name of the ESP Agent that you are applying the permission to. Use an asterisk to specify that all ESP Agents are affected by this permission. For example, the permission AGENTMSG.CONTROL.AIXUNIX determines if a user or group can or cannot issue ESP Agent control commands on the ESP Agent named AIXUNIX. The permission AGENTMSG.CONTROL.* determines whether a user or group can or cannot issue ESP Agent control commands on any ESP Agent in the topology. You can associate the following access values with this permission: • Allow enables a user or group to run the specified ESP Agent control command on the specified ESP Agent. • Deny restricts a user or group from running the specified ESP Agent control command on the specified ESP Agent. Note: The AGENTMSG permission works with the CMD permission. To issue ESP Agent control commands, a user also requires CMD.APPCMD* (Allow). For more information on the CMD permission, see “CMD” on page 80.
74 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Examples: AGENTMSG usage
Permission Definition AGENTMSG.CONTROL.A1* The user can issue ESP Agent control commands to all (Allow) ESP Agents whose name begins with A1. AGENTMSG.CONTROL. The user cannot issue ESP Agent control commands to A1UNIX (Deny) the ESP Agent named A1UNIX.
AGENTUSER Determines if a user can or cannot use a specific user ID on an ESP Agent.
Syntax AGENTUSER.agentname.userid where • agentname is the name of an ESP Agent that this permission affects. Use an asterisk to specify that all ESP Agents are affected by this permission. • userid is the name of a valid ESP Agent user ID. Use an asterisk to specify that all ESP Agent user IDs can be used. This value is case sensitive. For example, the permission AGENTUSER.A1UNIX.User1 determines whether a user can or cannot use the user ID User1 on the ESP Agent named A1UNIX. The permission AGENTUSER.*.* determines if a user can or cannot use any user ID on any ESP Agent in the topology. You can associate the following access values with this permission: • Allow enables a user or group to use the user ID specified in userid on the ESP Agent specified in agentname. • Deny restricts a user or group from using the user ID specified in userid on the ESP Agent specified in agentname.
Examples: AGENTUSER usage
Permission Definition AGENTUSER.A1*.* (Allow) The user can use any user ID on any ESP Agent in the topology whose name starts with A1. AGENTUSER.A1*.User1 The user can use the user ID User1 on any ESP Agent in (Allow) the topology whose name starts with A1. AGENTUSER.A1UNIX.* The user cannot use any user IDs on the ESP Agent (Deny) A1UNIX.
ESPD-5.0-AG-01 75 Section–Summary of security permissions
ALERT Determines a user or group’s access to Alert definitions. Alerts are used to take action automatically when a job reaches a particular stage of processing. This permission allows a user or group to view, define, modify, and delete an Alert.
Syntax ALERT.alertname where alertname is the name of the Alert you are applying the permission to. Use an asterisk to specify that the permission applies to all Alerts. You can associate the following access values with this permission: • Alter enables a user or group to create, delete, display, and update an Alert definition • Update enables a user or group to display and update an Alert definition. • Read enables a user or group to read an Alert definition.
Examples: ALERT usage
Permission Definition ALERT.* (Alter) User can create, delete, and change any Alert definition. ALERT.LATE_JOBS (Update) User can display and update the LATE_JOBS Alert definition. ALERT.FAIL* (Read) User can read any Alert definition starting with FAIL.
APPL Determines what a user or group can do using Workload Editor. With this permission, a user can create and view Applications as well as add, change, and delete Applications and job definitions.
Syntax APPL.applname where applname is the name of an Application. Use an asterisk to specify the permission determines access to all Applications. For example, the permission APPL.PAYROLL determines access to the Application PAYROLL. The permission named APPL.* determines access to all Applications.
76 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
You can associate the following access values with this permission: • Alter enables a user or group to • Create, delete, lock, and unlock an Application. • Add, change, and delete Applications and job definitions. • Unlock an Application definition locked by another user. • Update enables a user or group to • Lock or unlock an Application. • Add, change, and delete Applications and job definitions. • Read enables a user or group to download and display an Application.
Examples: APPL usage
Permission Definition APPL.* (Alter) The user can create and delete new Applications, change Applications, and change job definitions in any Applications. APPL.PAYROLL (Update) Add, change and delete job definitions in the Application called PAYROLL. APPL.PAYROLL (Read) The user can view the Application called PAYROLL.
ESPD-5.0-AG-01 77 Section–Summary of security permissions
APPLX Determines what a user or group can do in the Define perspective and also determines which jobs a user can view in the Scheduled Activity report. With this permission, a user or group can control and manage Applications, view states, insert jobs, and retrieve spool files.
Syntax APPLX.applname.jobname.jobqualifier.commandname where • applname is the name of the Application. Use an asterisk to specify that the permission determines access to all Applications. • jobname is the name of the job within the Application. Use an asterisk to specify the permission affects all jobs within the Application. • jobqualifier is the name of the job qualifier. • commandname is either subscribe or getspoolfile. Use an asterisk to specify the permission determines access to all Applications The subscribe value enables a user or group to display the status of jobs within Applications, but not control them. The getspoolfile value enables a user or group to view the output of a job in its spool file. The permission APPLX.*.*.*.subscribe gives users subscription-only access to all Applications. Users with this permission can view and monitor the status of jobs and Applications using the Define perspective, but they can’t issue any commands (for example, Complete, Bypass, Hold) to control the jobs and Applications. The Administrator can restrict users or groups so they can only subscribe to one Application in particular. To restrict users or groups to subscribe to one specific Application, the Administrator uses the following permission syntax: APPLX.applname.*.*.subscribe where applname is the name of the Application the Administrator wants to restrict subscription access to. You can associate the following access values with the APPLX permission: • Allow enables a user or group to run Applications or a job within an Application, issue commands against a job within an Application, and insert jobs into the Application. When the value subscribe is in the APPLX permission, the user or group can view the status of jobs, but cannot issue commands against them. • Deny restricts a user or group from running Applications or jobs within the Applications, issuing commands against jobs, or inserting jobs.
78 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Examples: APPLX usage
Permission Definition APPLX.* (Allow) The user can run all Applications and insert jobs in all Applications. APPLX.PAYROLL.* (Allow) The user can run and insert jobs in the Application PAYROLL. The user can also view Scheduled Activity reports that include this PAYROLL Application. APPLX.PAYROLL.PAYJOB1. The user can only run and insert jobs in the Application RUN1 (Allow) called PAYROLL, and can only affect the job PAYJOB1.RUN1. APPLX.PAYROLL (Deny) The user cannot run and insert jobs into the Application PAYROLL. APPLX.*.*.*.subscribe (Allow) The user can view and monitor the status of jobs and Applications using Workload Director. The user cannot issue any commands (for example, Complete, Bypasss, Hold) to control the jobs and Applications. APPLX.PAYROLL.*.*.subscribe The user can only view and monitor the status of jobs that (Allow) belong to the PAYROLL Application. APPLX.PAYROLL.*.*. The user can only view the spool file of jobs that belong to getspoolfile (Allow) the PAYROLL Application.
CALENDAR Determines a user or group’s access to Calendars. With this permission, a user can create new Calendars, add holidays and special day definitions, change remarks and workday settings, and reference a Calendar in Events.
Syntax CALENDAR.calendarname where calendarname is the name of the Calendar the permission defines access to. Use an asterisk to indicate this permission applies to all Calendars. For example, the permission CALENDAR.CALENDAR1 determines a user or group’s access to the Calendar named Calendar1. The permission CALENDAR.* determines a user or group’s access to all Calendars.
ESPD-5.0-AG-01 79 Section–Summary of security permissions
You can associate the following access values with this permission: • Alter enables a user or group to • Create and delete a Calendar. • Add holidays and special days. • Change remarks and workday settings. • Display a Calendar’s content. • Reference a Calendar in Events. • Update enables a user or group to • Add holidays and special days. • Change remarks and workday settings. • Display a Calendar’s content. • Reference a Calendar in Events. • Read enables a user or group to • Display a Calendar’s content. • Reference a Calendar in Events.
Examples: CALENDAR usage
Permission Definition CALENDAR.* (Alter) The user can create new Calendars, as well as view and modify all Calendars. CALENDAR.PAY* (Update) The user can view and modify any Calendar starting with PAY. CALENDAR.PAYROLL (Read) The user can display the Calendar called PAYROLL.
CMD Determines whether a user or group can or cannot issue commands from the Command Console.
Syntax CMD.APPCMD* You can associate the following access values with this permission: • Allow enables a user or group to issue commands from the Command Console. • Deny restricts a user or group from issuing commands from the Command Console.
80 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Examples: CMD usage
Permission Definition CMD.APPCMD* (Allow) The user can issue commands from the Command Console. CMD.APPCMD* (Deny) The user cannot issue commands from the Command Console.
EVENT Determines a user or group’s access to Event definitions. With the EVENT permission, a user or group can create, view, and modify Event definitions. Note: The EVENT permission works with the APPL permission. To create and update an Event, a user requires APPL (Alter) for the Application the Event refers to. For more information on the APPL permission, see “APPL” on page 76.
Syntax EVENT.eventprefix.eventname where • eventprefix is the prefix of the Event. • eventname is the name of the Event. You can associate the following access values with this permission: • Alter enables a user or group to create, delete, display and update an Event. • Update enables a user or group to display and update an Event. • Read enables a user or group to display a specific Event.
Examples: EVENT usage
Permission Definition EVENT.PROD.* (Alter) The user can create, modify and view all Event definitions with the PROD Event prefix. EVENT.PROD.PAYROLL The user can display and modify the Event called (Update) PAYROLL. EVENT.* (Alter) The user can create, modify and view all Event definitions. EVENT.TEST.MRC* (Update) The user can display and modify any Event that begins with MRC, with the Event prefix of TEST. EVENT.* (Read) The user can display all Events.
ESPD-5.0-AG-01 81 Section–Summary of security permissions
EVENTX Determines if a user or group can or cannot issue commands against an Event and determines which Events are included in the Scheduled Activity Report file.
Syntax EVENTX.eventprefix.eventname where • eventprefix is the prefix of the Event. • eventname is the name of the Event. You can associate the following access values with this permission: • Allow enables a user or group to issue commands to the Event. • Deny restricts a user or group from issuing commands to the Event.
Examples: EVENTX usage
Permission Definition EVENTX.* (Allow) The user can issue commands against all Events. EVENTX.PROD.* (Allow) The user can issue commands against all Events with the prefix PROD. EVENTX.PROD.PAYROLL The user cannot issue commands against the Event (Deny) PAYROLL, with the prefix, PROD. EVENTX.*.MYJOBS (Allow) The user can issue commands against all Events called MYJOBS. MYJOBS can have any prefix.
82 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
JAVASCRIPT Determines a user or group’s access to JavaScript scripts used in scheduling. This permission enables a user or group to view, modify, or create JavaScript scripts.
Syntax JAVASCRIPT.javascriptname where javascriptname is the name of a JavaScript script. You can associate the following access values with this permission: • Alter enables a user or group to create, delete, display and update a JavaScript script. • Update enables a user or group to display and update a JavaScript script. • Read enables a user or group to use a JavaScript script in an Application.
Examples: JAVASCRIPT usage
Permission Definition JAVASCRIPT.* (Alter) The user can create JavaScript scripts as well as view and modify all existing scripts. JAVASCRIPT. The user can view and modify the JavaScript script named DATEVARIABLES (Update) DATEVARIABLES. JAVASCRIPT.ODDJOBS The user can view the JavaScript script, named (Read) ODDJOBS, in Applications.
RESOURCE Determines a user or group’s access to resources used in scheduling. This permission enables a user or group to view, modify, or create resource definitions.
Syntax RESOURCE.resourcename where resourcename is the name of a resource. Use an asterisk to associate this permission with all resources. You can associate the following access values with this permission: • Alter enables a user or group to create, delete, display and update a resource definition. • Update enables a user or group to display and update a resource definition. • Read enables a user or group to use a resource definition in an Application.
ESPD-5.0-AG-01 83 Section–Setting up your ESP Server security network
Examples: RESOURCE usage
Permission Definition RESOURCE.* (Alter) The user can create new resource definitions as well as view and modify all existing resource definitions. RESOURCE.LOWPRIO The user can view and modify the resource definition (Update) called LOWPRIO. RESOURCE.DB2 (Read) The user can use the resource definition, DB2, in Applications.
Setting up your ESP Server security network
To ensure proper setup, use the following guidelines when you set up new users and groups at your installation: • Before you define security profiles, analyze your security needs to determine the similarities between different users. You will then have a rough idea of your needs for users and groups. • You can create groups that contain common permissions used by collections of users. • You can copy and modify the predefined users and groups if you need to create security profiles with similar permission requirements. • Maintain an organized set of naming conventions for your security profiles. For example, you could organize your security profiles based on user location or job description.
Example scenarios This section contains some example scenarios that you may find helpful in setting up your own ESP Server security network.
Scenario 1 This scenario shows how you can set up a simple security system using only the predefined users and groups. The following table contains a list of staff members and their roles.
Name Function Andrea Administrator Barry Administrator Chantal Scheduler
84 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Name Function Dean Scheduler Erin Scheduler Bob Scheduler Fred Operator Gail Operator Hugh Operator Ingrid Operator Jerry Operator
To set up this security scenario 1. Open the Security Profiles Manager. 2. Select Users from the main window. 3. Click Add. The Add User dialog appears. 4. Fill in the User ID, User name, Password, and Confirm password fields using the information in the following table.
User ID User name Password Confirm Password A_ANDREA Andrea a1 a1 A_BARRY Barry b2 b2 S_CHANTAL Chantal c3 c3 S_DEAN Dean d4 d4 S_ERIN Erin e5 e5 S_BOB Bob b6 b6 O_FRED Fred f7 f7 O_GAIL Gail g8 g8 O_HUGH Hugh h9 h9 O_INGRID Ingrid i10 i10 O_JERRY Jerry j11 j11
The user IDs in this scenario use the following naming convention: • Administrator user IDs begin with A_. This prefix is followed by the user’s name, for example, A_Andrea. • Scheduler user IDs begin with S_. This prefix is followed by the user’s name, for example S_CHANTAL. • Operator user IDs begin with O_. This prefix is followed by the user’s name, for example O_FRED.
ESPD-5.0-AG-01 85 Section–Setting up your ESP Server security network
5. To add these user IDs to groups, copy the group lists from the predefined users using the information below.
User ID Copy Group List from User... A_ANDREA ADMIN A_BARRY ADMIN S_CHANTAL SCHEDMASTER S_DEAN SCHEDMASTER S_ERIN SCHEDMASTER S_BOB SCHEDMASTER
Because there is not a predefined user ID for operators, add the following user IDs to the group OPERGRP: • O_FRED • O_GAIL • O_HUGH • O_INGRID • O_JERRY 6. Once you have assigned groups to all the users, you can now add permissions. To add permissions to the user IDs, copy the permission lists from the predefined users using the information below.
User ID Copy Permissions from User... A_ANDREA ADMIN A_BARRY ADMIN S_CHANTAL SCHEDMASTER S_DEAN SCHEDMASTER S_ERIN SCHEDMASTER S_ERIN SCHEDMASTER S_BOB SCHEDMASTER
7. Define permissions for operators for remaining User IDs. 8. Notify the users of their user IDs and passwords. Request that they change their passwords immediately.
Scenario 2 This scenario builds on the previous scenario. It shows a typical ESP Server installation and illustrates most ESP Server security features. Following this scenario are some examples that show some maintenance situations relative to this scenario.
86 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Specifications In this scenario • The company head office is located in Toronto with branches in New York and London. A different set of ESP Agents is installed in each branch. • Two administrators and a master scheduler are located in Toronto. The master scheduler needs access to everything at both a scheduling and operating level. • There is one scheduler located in Toronto and one each in New York and London. These schedulers work exclusively on their own branches’ data. The policy is that schedulers can only operate for test Applications. • There are three operators in Toronto and one each in New York and London. • There is one tape drive resource in each branch (Toronto, New York, and London). Only the branch operators can control the tape drives. • One of Toronto’s operators is the only person authorized to run payroll jobs. • The training department periodically conducts operator training in Toronto and requires new users with authorization to run a set of training jobs, and to view all jobs running at every branch. The following table summarizes the staff organization.
User Name Position Location Security Requirements Andrea Administrator Toronto • Administrate and view everything Barry Administrator Toronto • Administrate and view everything Chantal Master Scheduler Toronto • Schedule all work • Run all work Dean Scheduler Toronto • Schedule Toronto work • Run Toronto test work Bob Scheduler New York • Schedule New York work • Run New York test work Erin Scheduler London • Schedule London work • Run London test work Fred Operator Toronto • Run Toronto work • Run payroll work • Control Toronto tape drive Gail Operator Toronto • Run Toronto work Hugh Operator Toronto • Run Toronto work
ESPD-5.0-AG-01 87 Section–Setting up your ESP Server security network
User Name Position Location Security Requirements Ingrid Operator New York • Run New York work • Control New York tape drive Jerry Operator London • Run London work • Control London tape drive Training ID, as Operator trainee Toronto • Run training work needed • Monitor all work
This scenario uses the following naming conventions for users, groups, and permissions: • User IDs in this scenario use the following naming convention: • Administrator user IDs begin with A_ • Scheduler user IDs begin with S_ • Operator user IDs begin with O_ • City codes will be used for the names of most elements of ESP Server. The city codes are as follows: • Toronto: TOR_ • New York: NY_ • London: LON_ • ESP Agent names in the topology will use the city code. For example, all ESP Agents at the Toronto location will start with TOR_. • Application names will use the city code. The exception to this is payroll Applications, which will start with PAY, and training Applications, which start with TRN. Test Applications use the city code followed by TST. • Events and Event prefixes will use the city code. The exceptions are payroll Event prefixes, which start with PAY, test Events, which start with TST, and training Event prefixes, which start with TRN. • Calendar names, Resource names, and Alert names will use the city code.
Implementation
Creating groups
ADMIN1 Position: Administrators
To create the ADMIN1 group 1. Create a new group, ADMIN1. 2. Copy all permissions to ADMIN1 from the predefined group, ADMINGRP.
88 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
3. Add the following permissions: • ALERT.* (Read) • APPL.* (Read) • CALENDAR.* (Read) • EVENT.*.* (Read) • Resource.*.* (Read)
TOR_SCHED1 Position: Toronto Schedulers
To create the TOR_SCHED1 group 1. Create a new group, TOR_SCHED1. 2. Copy all permissions to TOR_SCHED1 from the predefined group, SCHEDGRP. 3. Update the following permissions • AGENT.* (Allow) • ALERT.* (Alter) • APPL.* (Alter) • APPLX.* (Allow) • CALENDAR.* (Alter) • EVENT.*.* (Alter) • EVENTX.*.* (Allow) to the following: • AGENT.TOR_* (Allow) • ALERT.TOR_* (Alter) • APPL.TOR_* (Alter) • APPLX.TOR_TST*.* (Allow) • CALENDAR.TOR_* (Alter) • EVENT.TOR_*.* (Alter) • EVENTX.TOR_TST*.* (Allow)
TOR_OPGRP1 Position: Toronto Operators
To create the TOR_OPGRP1 group 1. Create a new group, TOR_OPGRP1. 2. Copy all permissions to TOR_OPGRP1 from the predefined group, OPERGRP.
ESPD-5.0-AG-01 89 Section–Setting up your ESP Server security network
3. Update the following permissions • ALERT.* (Read) • APPL.* (Read) • APPLX.* (Allow) • EVENT.*.* (Read) • EVENTX.*.* (Allow) to the following: • ALERT.TOR_* (Read) • APPL.TOR_* (Read) • APPLX.TOR_* (Allow) • EVENT.TOR_*.* (Read) • EVENTX.TOR_*.* (Allow) 4. Add the following permissions: • RESOURCE.TOR_TAPE (Alter) • CMD.APPCMD* (Allow) • AGENT.TOR_* (Allow)
TOR_OPRTRAIN Position: Operator Trainee
To create the TOR_OPTRAIN group 1. Create a new group called TOR_OPTRAIN. 2. Copy all permissions to TOR_OPTRAIN from the predefined group, OPERGRP. 3. Update the following permissions: • APPLX.* (Allow) • EVENTX.*.* (Allow) to the following: • APPLX.TRN* (Allow) • EVENTX.TRN*.* (Allow) 4. Add the permission CMD.APPCMD* (Allow)
90 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Creating groups for New York and London Once groups for Toronto have been created, you can now create groups for New York and London.
To create groups for New York and London 1. Create the following groups: • NY_SCHED1 • LON_SCHED1 • NY_OPGRP1 • LON_OPGRP1 2. Copy the permissions for each new scheduler group from TOR_SCHED1 and the permissions for each new operator group from TOR_OPGRP1. 3. Modify the permissions of the new groups to reflect the new city codes. For example, in NY_OPGRP1, when you copy the permissions from TOR_OPGRP1, you must change ALERT.TOR_* (Read) to ALERT.NY_* (Read).
Creating users You have now created all the groups required. You must now create users based on the information in the job summary table. Most of the permissions the users will need are already defined in their respective groups, but you will need to customize some users based on some exact criteria in their security requirements.
To create users 1. Create the following users using the table below for their User IDs, user name, passwords, and group association.
User ID User Name Password/ Groups Confirm Password A_ANDREA Andrea a1 ADMIN1 A_BARRY Barry b2 ADMIN1 S_CHANTAL Chantal c3 TOR_SCHED1 NY_SCHED1 LON_SCHED1 TOR_OPGRP1 NY_OPGRP1 LON_OPGRP1 S_DEAN Dean d4 TOR_SCHED1 S_BOB Bob e5 NY_SCHED1 S_ERIN Erin f6 LON_SCHED1 O_FRED Fred g7 TOR_OPGRP1
ESPD-5.0-AG-01 91 Section–Setting up your ESP Server security network
User ID User Name Password/ Groups Confirm Password O_GAIL Gail h8 TOR_OPGRP1 O_HUGH Hugh i9 TOR_OPGRP1 O_INGRID Ingrid j10 NY_OPGRP1 O_JERRY Jerry k11 LON_OPGRP1
Note: The user, S_CHANTAL belongs to all groups because, as master scheduler, she needs access to everything. 2. Add the following permissions to O_FRED, who needs to run payroll jobs: • APPLX.PAY* (Allow) • EVENTX.PAY* (Allow) 3. Notify users of their user ID and password. Request that they change their passwords immediately.
Maintenance examples The following examples are based on changes made to the above scenario.
New employee Kirk has joined the company as an operator. He will work in New York, but first he will be trained in Toronto for three months.
Creating a user profile for Kirk 1. For the training period, set the user as follows.
User ID User Name Password/Confirm Groups Password O_KIRK Kirk l11 TOR_OPTRAIN
2. Inform Kirk of his user ID and password and request that he change his password. 3. When he assumes his position in New York, remove him from TOR_OPTRAIN group and add him to NY_OPGRP1.
Employee leaving Fred is leaving the company. Delete him from the user list and, because he was the only user allowed to run payroll Applications, you need to inquire about who will replace him and move the APPLX.PAY* (Allow) and EVENTX.PAY* (Allow) permissions to the new user.
92 ESPD-5.0-AG-01 Chapter 5–Establishing and Controlling Security
Employee transfer Gail is promoted from operator to scheduler. She will stay in New York. Create a new user ID called S_GAIL and add it to the group NY_SCHED1. Delete the user O_GAIL. It is possible Gail will combine her old and new duties during a transition period. You may want to assign S_GAIL to the NY_OPGRP1 group temporarily.
New department The company expands and opens a branch in Los Angeles. The staffing will be as follows.
User Name Position Location Security Requirements Leslie Scheduler Los Angeles • Administrate Los Angeles installation • Schedule Los Angeles work • Run Los Angeles test work Michael Operator Los Angeles • Run Los Angeles work • Control Los Angeles tape drive Helen Operator Los Angeles • Run Los Angeles work
The city code for Los Angeles is LA_.
To set up security for the new department in Los Angeles 1. Create the groups, LA_SCHED1 and LA_OPGRP1. Copy and modify the permissions from TOR_SCHED1 and TOR_OPGRP1, respectively. 2. Create the following users.
User ID User Name Password/Confirm Groups Password S_LESLIE Leslie m12 LA_SCHED1 O_MICHAEL Michael n13 LA_OPGRP1 O_HELEN Helen o14 LA_OPGRP1
3. Add the following permissions to the user S_LESLIE, to give her access to administrative functions: • ADMIN.Network Topology (Alter) • ADMIN.Security Files (Alter)
ESPD-5.0-AG-01 93 Section–Setting up your ESP Server security network
94 ESPD-5.0-AG-01 Handling Cybermation ESP Server Log Files
This chapter contains the following topics: • About log files • Changing a log’s location or name • Creating an audit log report • Filtering messages sent to trace logs • Summary of filter IDs
ESPD-5.0-AG-01 95 Section–About log files
About log files
ESP Server maintains three log file types that store diagnostic and auditing information: • Trace logs • Automated Framework Message logs • Audit logs The trace log (tracelog.txt) stores communication messages between Cybermation ESP system components and maintains debugging information used primarily for diagnostic purposes. The AFM log (afmlog.txt) stores communication messages between ESP Server, ESP Agents, ESP Desktop Client and ESP Web Client. The audit log records user input. ESP Server creates a new audit log every day. You cannot change the frequency ESP Server creates the audit log. By default, ESP Server names the audit log audit.YYYYMMDD.txt, where YYYYMMDD is the log date. Unlike the other logs, the audit log is encrypted. You cannot use ESP Server to automatically archive or clear the audit log. You can create an HTML and Comma Separated Values (CSV) report using the auditlog export command in the Command Console.
Log maintenance By default, ESP Server performs an automatic archive, or rotation, of all its log files at midnight. During the rotation, ESP Server archives the log files, creating new files in the LogFiles directory. ESP Server includes a timestamp in the filename of the archived log, indicating when ESP Server archived the file.
Related topics • “Archiving server log files” on page 157 • “Clearing server log files” on page 159 • “Clearing server.log files (UNIX systems only)” on page 161
Filter IDs Each message ESP Server sends has an associated filter ID. Filter IDs enable you to filter the messages ESP Server writes to logs. When you apply filter IDs to a log, ESP Server logs all messages with filter ID numbers equal to the specified filter IDs. By default, ESP Server sets the filter IDs of the logs to 0. Note: ESP Server logs exception messages automatically. Exception messages do not have filter IDs associated with them.
96 ESPD-5.0-AG-01 Chapter 6–Handling Cybermation ESP Server Log Files
Changing a log’s location or name
By default, ESP Server maintains the logs in the following directory: • On UNIX:
To change a log file’s location or name 1. Open the espresso.properties file located in ESP Server installation directory. You can edit the espresso.properties file using your operating system’s text editor. 2. Edit the log file’s targets field. • cybtracelog.targets — The trace log’s file location • cybafmlog.targets — The AFM log’s file location • cybauditlog.targets — The audit log’s file location 3. Recycle ESP Server.
Example: Changing the name and location of the trace log file A user changed the name and location of the trace log file by modifying the cybtracelog.targets field of the espresso.properties file. The cybtracelog.filterids field specifies the filter IDs applied to the log. The name and location changes are in bold. cybtracelog.filterids=0 cybtracelog.targets=/u1/Espresso/Logs/Preferredtracelog.txt
ESPD-5.0-AG-01 97 Section–Creating an audit log report
Creating an audit log report
The audit log report contains every user-initiated ESP Server command. To create an audit log report, you use the auditlog export appcmd. This command creates an audit log in CSV format and a report in html format. For each command a user issues, the audit log records the following information: • Date and time the user issued the command • User ID that issued the command • Command type • Command name • Command message (AFM) Note: To export the audit log, you must have administrative privileges.
To generate an audit log report 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Issue the following command: auditlog export path(directory_path) name(name) [startdate(YYYYMMDD)] [enddate(YYYYMMDD)] where • directory_path is the full directory path on the server where you want to export the audit log and generate the report. • name is the name you want to use for the audit log and audit report. ESP Server names the audit log name.log (in CSV format) and the report name.html. Note: The name can contain any allowable filename character determined by the operating system where ESP Server is installed. • startdate and enddate are optional parameters. If you omit the start and end dates, ESP Server exports the audit log of the current day, for example auditlog export path(/export/home/usr) name(today). If you enter only the start date, ESP Server assumes the end date is the current day, for example auditlog export path(/export/home/usr) name(Mar15)startdate(20050315).
98 ESPD-5.0-AG-01 Chapter 6–Handling Cybermation ESP Server Log Files
Note: If you enter an end date, you must enter a start date. If you enter a start date and an end date, ESP Server exports the audit log between the two dates, for example auditlog export path(/export/home/usr) name(Mar15to31)startdate(20050315)enddate(20050331).
Filtering messages sent to trace logs
To reduce the number of messages written to logs, apply filter IDs to the logs. You can apply temporary filter IDs or permanent filter IDs.
Applying temporary tracelog filter IDs You can add filter IDs temporarily using the filterid command in the Command Console. These filter IDs apply until you restart ESP Server. Use this method to monitor specific messages for a limited time. You can temporarily add and remove a single filter ID, multiple filter IDs, or a range of filter IDs to a log file.
To add temporary filter IDs to a trace log 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: tracelog filterid(nnnn) where nnnn is the number of a valid filter ID. For multiple filter IDs use (nnnn, nnnn). For a range of filter IDs, use (nnnn-nnnn)
To remove temporary filter IDs from a trace log 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: tracelog filterid(-nnnn) where nnnn is the number of a valid filter ID. For multiple filter IDs use (-nnnn, -nnnn). For a range of filter IDs, use (-nnnn-nnnn)
ESPD-5.0-AG-01 99 Section–Filtering messages sent to trace logs
Examples: Applying temporary tracelog filter IDs • tracelog filterid(909)adds filter ID 909 to the trace log • tracelog filterid(23,909)adds filter IDs 23 and 909 to the trace log • tracelog filterid(955-957)adds filter IDs 955, 956, and 957 to the trace log
Examples: Removing temporary tracelog filter IDs • To remove filter ID 909 from the trace log, enter tracelog filterid(-909) • To remove filter IDs 23 and 909 from the trace log, enter tracelog filterid(-23,-909) • To remove filter IDs 900 to 905 from the trace log, enter tracelog filterid(-900-905)
Applying permanent tracelog filter IDs You can add filter IDs permanently by modifying the espresso.properties file. These filter IDs apply after you restart ESP Server. You can permanently add and remove a single filter ID, multiple filter IDs or a range of filter IDs to a log file.
To apply a permanent filter ID to a trace log 1. Open the espresso.properties file located in the ESP Server installation directory. You can edit the initialization parameter file using your operating system’s text editor. 2. Edit the trace log file’s cybtracelog.filterids field. 3. Recycle ESP Server.
Example: Applying permanent tracelog filter IDs A user has permanently added filter IDs to the trace log by modifying the cybtracelog.filterids field of the espresso.properties file. The cybtracelog.targets field specifies the name and location of the trace log affected by the filter IDs. The filter ID change is in bold. cybtracelog.filterids=0,604 cybtracelog.flush=true cybtracelog.targets=
100 ESPD-5.0-AG-01 Chapter 6–Handling Cybermation ESP Server Log Files
Summary of filter IDs
The following filter IDs apply to ESP Server.
Filter IDs Informational Messages From... 0 Lowest-level messages including exception messages 1 Common library server functions 5 Common library utilities 10 Performing synchronization 11 The publish/subscribe framework (for example, TimerPop) 13 The library database 14 The communication framework 15 Directing Events 17 Processing Email requests 18 Informational messages from administering ESP Server licenses 19 Subscriptions and publications of scheduled Events 33 The Application Registry framework (for internal use only) 37 Communication between the Command Console and ESP Server 47 Relational database actions 48 SNMP handling 501 The Configuration Server 502 Processing Configuration Server parameters 503 Common utilities used by the Configuration Server (for internal use only) 504 Ready for processing regular commands 505 Management for commands entered through the Command Console 506 The communications for the Configuration Server 510 Managing the Configuration Server data sources 511 Configuration Server tag manager (for internal use only) 512 Configuration Server event notification framework used by the tag manager (for internal use only) 514 Messages received from ESP Desktop Client users 515 End of session 526 Input message timings 601 The Scheduler Server 602 Utilities used by the Scheduler Server 603 The Scheduler Server publish/subscribe framework (for internal use only) 604 Errors encountered by processing commands entered from the Command Console 606 Scheduler Server management of Application definitions (Sheet 1 of 3)
ESPD-5.0-AG-01 101 Section–Summary of filter IDs
Filter IDs Informational Messages From... (Continued) 607 Communication framework of the Scheduler Server 610 The Scheduler Server processing TDR definitions 611 Scheduler Server management of Event definitions 612 Scheduler Server management of Calendar definitions 613 Scheduler Server timer framework (for internal use only) 617 Messages accepted by an input conversation 618 Messages queued at the end of a conversation 622 Time publisher status at warm start initialization 626 Input message timings 628 Processing of Alerts 629 Scheduler Server management of scheduled activities 701 ESP Desktop Client 702 Utilities used by the Workstation Server 703 The Command Console 707 Messages exchanged between the ESP Desktop Client and the Workstation Server 708 Informational messages from ESP Desktop Client session subscription 901 The Manager 902 Utilities used by ESP Server Manager 903 Managing the topology 904 The publish/subscribe framework (for example, TimerPop) 905 Managing jobs in the Manager 906 Manager commands entered from ESP Desktop Client 907 Processing commands entered from the Command Console 909 Processing internal commands 910 The communications for the Manager 912 Email notifications from the Manager 914 Processing publish/subscribe criteria (for internal use only) 916 Processing of resource acquisition within the Manager 919 Accepted input messages in a conversation 920 Messages queued to the input queue on exit 922 Workflow objects at warm start initialization 923 Relationship publisher manager at warm start initialization 924 Release publisher manager at warm start initialization 925 Time publisher manager at warm start initialization 926 Output message queue at initialization 927 Output message queue manager destinations (Sheet 2 of 3)
102 ESPD-5.0-AG-01 Chapter 6–Handling Cybermation ESP Server Log Files
Filter IDs Informational Messages From... (Continued) 928 Input message timings 1001 The Resource Server 1002 The Resource Server Utilities 1005 Communication framework of the Resource Server 1006 Resource Server management of resource definitions 1007 Resource Server resource acquiring/returning processing 1008 Processing commands and state changes in the resource components 1009 Storing and retrieving ESP High Availability/warm-start related status (Sheet 3 of 3)
ESPD-5.0-AG-01 103 Section–Summary of filter IDs
104 ESPD-5.0-AG-01 Administering ESP High Availability
This chapter contains the following topics: • ESP High Availability terminology • The ESP High Availability process • Configuring ESP High Availability detection • Changing the type of failback • Switching Primary and Standby roles • Converting to an ESP High Availability installation • Verifying the ESP High Availability configuration • Preventing auto connection to the Standby
ESPD-5.0-AG-01 105 Section–ESP High Availability terminology
ESP High Availability terminology
ESP High Availability is the ESP Server failure detection and recovery process for ESP Server. The process involves switching workflow processing from one server (the Primary) to a backup server (the Standby) when a failure occurs on the Primary. The following terms describe ESP High Availability terminology:
Primary Primary refers to the ESP Server that currently controls the workflow and interacts with ESP Agents defined in the Topology view to run jobs.
Standby Standby refers to the ESP Server that currently runs as a backup server. When ESP High Availability occurs, the Standby becomes the Primary.
ESP High Availability recovery ESP High Availability recovery (failback) refers to the workflow control returning to the preferred server.
Preferred server You specify which server is the preferred server during the installation. With automatic failback, the preferred server (Preferred) refers to the server peer that becomes the Primary when it starts up. If, after ESP High Availability has occurred, the non-preferred server is Primary and the preferred server starts up, the preferred server becomes the Primary and the non-preferred server becomes the Standby. With manual failback, the preferred server does not take over at start up. You must issue a changerole command for failback to occur.
Database failover Database failover refers to the process of running a backup (Standby) database server to take over should the Primary (production) database fail.
106 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
The ESP High Availability process
A typical ESP High Availability configuration, as shown in the diagram below, consists of two ESP Servers installed on separate machines. Both servers use the same relational database management system (RDBMS) and shared file system.
During ESP Server startup When an ESP Server starts up, it always begins in Standby mode. During startup, it monitors the other ESP Server. • If the started ESP Server detects that the other server is unavailable, that ESP Server runs as the Primary. • If the started ESP Server detects that the other server is running in Primary mode, the server • Becomes the Primary if it is the preferred server and automatic failback is configured. • Remains as the Standby if it is not the preferred server or automatic failback is not configured. • If the started ESP Server detects that the other server is running in Standby mode (because both servers started at the same time), a vote takes place between the servers to decide which one will become the Primary. In this case, the preferred server becomes the Primary.
ESPD-5.0-AG-01 107 Section–The ESP High Availability process
At any time, you can issue a changerole command from either server to have the servers change modes. After issuing the command, the Primary becomes the Standby and the Standby becomes the Primary.
During ESP High Availability detection During normal processing, the Primary runs the workflow and the Standby monitors the Primary for failure. Since the Primary and Standby share the same database, no data replication or extra processing takes place. The Standby monitors the Primary or monitors the database upon monitoring failure. ESP High Availability occurs if either of the following situations occur: • The Primary machine goes down. • ESP Server on the Primary terminates. To determine if failure has occurred, the ESP High Availability detection mechanism uses a dual- stage failure detection process.
Stage 1 monitoring: Heartbeat If both servers are running, the Standby periodically contacts the Primary based on the configured heartbeat.
If the servers can communicate directly with each other, monitoring continues according to the configured frequency. If the servers cannot communicate directly, stage 2 monitoring takes place.
Stage 2 monitoring: Relational database In stage 2 monitoring, ESP Server uses the relational database as the communication method. Since both servers require database access to operate, ESP Server uses the database as the final arbiter to determine whether failure has occurred on the Primary. During stage 2 monitoring, the Primary periodically updates a table in the database. The Standby monitors (polls) this table to verify that the Primary is still active. Before each database poll, the Standby attempts to contact the Primary (stage 1 monitoring). You can configure how often the Primary updates the database and how long before the Standby monitors the database.
108 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
If the Standby detects the Primary through updates to the database, ESP High Availability does not occur. The Standby continues to monitor. If the Standby cannot detect the Primary after the specified polling interval, ESP High Availability occurs.
During ESP High Availability Assuming the Standby is running at the time of failure, ESP High Availability is automatic. If both stage 1 and stage 2 monitoring fail, ESP High Availability occurs as follows: • The Standby performs a warm start. • The Standby begins running the workflow. • The Standby contacts ESP Agents to inform them to communicate with the server • ESP Server on the Standby sends an SNMP message and email to notify you that the Primary has failed and that the Standby is now running workflow as the Primary.
During ESP High Availability recovery After ESP High Availability has occurred, processing can resume on the preferred server once the preferred server restarts. You can configure this failback to be automatic or manual. In automatic failback, once the preferred server restarts, it resumes its role as the Primary. Upon starting, the preferred server sends a changerole request to the current Primary. Upon receiving the change request, the current Primary quiesces the server components and returns to Standby mode. Once the server returns to Standby mode, the preferred server runs as the Primary.
ESPD-5.0-AG-01 109 Section–Configuring ESP High Availability detection
In manual failback, once the preferred server restarts, it runs in Standby mode. You can issue a changerole command to either server. After issuing the changerole command, the current Primary becomes the Standby and the current Standby becomes the Primary.
During database failure If the Primary (production) database fails, ESP Server goes into standby. You can configure ESP Server to use a Standby database so ESP Server can continue processing workflow.
Related topics • For information on connecting to a standby database, see “Changing the relational database connectivity properties” on page 104. • For information on implementing a disaster recover solution using the Oracle 10g database, see “Implementing a disaster recovery solution” on page 106.
Configuring ESP High Availability detection
You can configure ESP High Availability detection using the ESP Desktop Client Topology view. ESP Server uses the ESP High Availability detection settings at the following times: • Upon startup to check whether the each server is running • During normal operation. The Primary processes the workflow and the Standby monitors the Primary.
To configure ESP High Availability detection 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. Right-click the ESP Server node and select Configure Shared Parameters. 5. Click the ESP High Availability tab. 6. Enable ESP High Availability by setting the Enable ESP High Availability field to true.
110 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
7. Configure these mandatory ESP High Availability settings. • Frequency (in seconds) To Poll Server — The frequency at which the Standby monitors the Primary during stage 1 monitoring (heartbeat method). • Primary Server Frequency (in seconds) To Update Database — The update frequency. This value sets the frequency at which the Primary updates the database (relational database method). • Standby Server Factor To Poll The Database — The polling factor. ESP Server uses this value to compute the polling interval, which is the elapsed time between stage 1 failure and the time the Standby monitors the database. Note: The Primary Server Frequency and the Standby Server Factor to Poll the Database properties work together to determine the polling interval as follows: Polling Interval = Primary Server Frequency x Standby Server Factor to Poll the Database Tip: The polling interval determines the ESP High Availability latency — the time it takes ESP Server to recognize failure has occurred on the Primary and begin to switch to the Standby. You may want to increase the polling interval to give you time to fix the problem on the Primary. Or you may want to keep the polling interval low to minimize the amount of time ESP Server is down (but increasing the chance ESP High Availability occurs). 8. If desired, set the Enable Automatic Failback to Preferred Server field to true. • With automatic failback, control of the workflow automatically fails back to the preferred server. The non-preferred server becomes the Standby. • With manual failback, you can force control of the workflow to fail back to the other server by issuing a command. 9. Click OK. 10. Recycle ESP Server.
Related topic “Recycling the server” on page 20
ESPD-5.0-AG-01 111 Section–Changing the type of failback
Changing the type of failback
You can change the type of failback from manual to automatic or automatic to manual. Failback can occur at the following times: • When the preferred server starts (or restarts after ESP High Availability) — If failback is automatic, control of the workflow automatically fails back to the preferred server. The non-preferred server becomes the Standby. • At user request — If failback is manual, you can force control of the workflow to fail back to the other server by issuing a command.
To change the type of failback 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. Right-click the ESP Server node and select Configure Shared Parameters. 5. Click the ESP High Availability tab. 6. In the Enable Automatic Failback to Preferred Server field, change its value. • true — At startup, the preferred server becomes the Primary. • false — At startup, the preferred server remains the Standby if the non- preferred server is running. 7. Click OK. 8. Recycle ESP Server.
Related topic “Recycling the server” on page 20
Switching Primary and Standby roles
After you issue the changerole command, the current Primary becomes the Standby and the current Standby becomes the Primary.
To change the ESP Server role from Standby to Primary 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console.
112 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
4. Enter the following command: changerole
Converting to an ESP High Availability installation
This section explains how to convert your existing stand-alone ESP Server installation to an ESP High Availability installation. The process assumes you have one ESP Server instance installed that is not enabled for ESP High Availability, and you are making this instance the Primary. To determine the minimum hardware and system requirements of a Primary and Standby, refer to the Installing Cybermation ESP: dSeries guide. Use that guide to plan the configuration parameters that you need as you follow the steps described in this section. The following sections show two configuration models for ESP High Availability installations.
ESPD-5.0-AG-01 113 Section–Converting to an ESP High Availability installation
ESP High Availability configuration 1 In this configuration, you install ESP Server on one machine, which you designate as the preferred server. You install ESP Server again on a different machine. The preferred server acts as the Primary and the second server acts as the Standby. The Primary and Standby use a shared-file system and relational database, which you install on a separate machine.
Failover configuration 2 In this configuration, you install ESP Server on one machine, which you designate as the preferred server. You install ESP Server again on a different machine. The preferred server acts as the Primary and the second server acts as the Standby. The
114 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
Primary and Standby use a shared-file system you install on a separate machine. You also install a primary database on its own machine and a standby database on its own machine.
Setting up ESP High Availability Complete these tasks to convert your existing installation to a ESP High Availability installation.
Step Activity Page 9 1. Check the ESP High Availability requirements. 115 2. Stop ESP Server. 116 3. Set up a shared-file system. 116 4. Set up your Primary. 116 5. Start the Primary. 117 6. Install the Standby. 117 7. Start the Standby. 118
Check the ESP High Availability requirements If you are configuring ESP High Availability, install the Standby on a different machine than the Primary. The Standby machine’s system requirements are the same as the Primary machine’s.
ESPD-5.0-AG-01 115 Section–Converting to an ESP High Availability installation
The system clocks on the two machines must be within 500 milliseconds of each other. Note: The systems synchronize when you connect them to a time server. You can also check if the systems are synchronized by connecting to each one and checking the time. If you install the Primary and Standby in different time zones, in an ESP High Availability situation ESP Server might run workload twice or skip scheduled jobs. To prevent this problem, ensure the Primary and Standby use the same time zone. You can only install one pair of primary and standby servers per ESP High Availability configuration.
Stop ESP Server Before stopping ESP Server, ensure that no jobs are currently running or active on the ESP Server instance you want to configure as your Primary.
Set up a shared-file system ESP Server uses a shared file system for ESP High Availability configurations. The shared file system stores PSE Pro Object Database files. Have your System or Network Administrator set up the shared file system required by the Primary and Standby. When you install, both ESP Servers require access to this shared file system. Ensure the user accounts under which the Primary and Standby run have access to this shared location on the network. Note: On average, a size of 10GB should be adequate for the shared file system.
Set up your Primary 1. Start the ESP Server installation program on your Primary machine. 2. Use the following table to guide you through the installation of the Primary.
Install Section Value to use Installation Path ESP Server installation directory of the server you want to designate as Primary Existing Cybermation ESP Server Choose I want to reinstall ESP Server and preserve Installation my existing configuration. Select Backup Option Select Yes to backup your existing installation. Choose Backup Folder Enter your backup folder or accept the default. Configure database Select No. ESP High Availability Select Yes.
116 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
3. When Local Server with ESP High Availability appears, do the following: • To designate this ESP Server as the Primary, select Preferred Server. • Enter a port number, if different than the default, and the path to your shared directory. Record these values to use when you install the Standby.
Field Your Value Peer Server Manager Port Shared Directory
4. When Failback Type appears, choose whether to enable automatic failback. 5. When ESP High Availability Settings, specify new settings or accept the defaults. 6. Complete the remainder of the installation.
Related topics • For more information on the installation program, refer to the Installing Cybermation ESP: dSeries guide. • To understand automatic failback, see “Changing the type of failback” on page 112. • To understand the ESP High Availability detection settings, see “Configuring ESP High Availability detection” on page 110.
Start the Primary The Primary and Standby share a file that stores the shared properties used by the two servers. To transfer the shared properties to the database, you must start the Primary before you install the Standby.
Install the Standby Install a second instance of ESP Server to serve as the Standby in your ESP High Availability configuration.
To install the Standby 1. Start the ESP Server installation program on your Standby machine. 2. When you are prompted to configure ESP High Availability, select Y. 3. When Local Server with ESP High Availability appears, do the following: • To designate this ESP Server as the Standby, ensure the Standby option is selected. • For the Peer Server Manager Port, enter the value you set for the Primary. Refer to the value you recorded. • For the Shared Directory, enter the path to your shared directory.
ESPD-5.0-AG-01 117 Section–Verifying the ESP High Availability configuration
4. Complete the remainder of the installation. 5. When the installation is complete, ensure you have replaced your temporary license.
Start the Standby Start the Standby. Your Primary should already be started.
Verifying the ESP High Availability configuration
This section assumes you have successfully started both the Primary and Standby and your default ESP Agent is running. To verify the ESP High Availability configuration, complete the following steps.
Step Activity Page 9 1. Trigger and monitor the VERIFY Application on the Primary. 118 2. Start the SNMP Message Viewer. 118 3. Change the Primary and Standby roles. 119 4. Trigger and monitor the VERIFY Application on the Standby 119 (now acting as Primary).
Trigger and monitor the VERIFY Application on the Primary 1. Using ESP Desktop Client, connect to the Primary. 2. Using the Services perspective, open the Event view and trigger the CYBERMATION.VERIFY Event. 3. Using the Monitor perspective, view the generation of the VERIFY Application. The Application should complete successfully.
Start the SNMP Message Viewer To verify that the Primary and Standby have changed roles, you need to start the SNMP Trap Receiver. 1. If not connected, connect to the Primary using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the SNMP Message Viewer. 4. Click the Start SNMP receiver icon. The Start SNMP Trap Receiver and Set Port dialog appears.
118 ESPD-5.0-AG-01 Chapter 7–Administering ESP High Availability
5. In the Port Number field, enter the port number and click OK. The SNMP Message Viewer begins capturing SNMP messages.
Change the Primary and Standby roles 1. If not connected, connect to the Primary using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: changerole
5. Open the SNMP Message Viewer. Check the SNMP messages to verify that the Standby has become the Primary.
Related topics For more information on SNMP ESP High Availability messages, see “About SNMP messages” on page 122.
Trigger and monitor the VERIFY Application on the Standby (now acting as Primary) 1. After the servers complete changing roles, connect to the Standby (now acting as Primary). 2. Using the Services perspective, open the Event view and trigger the CYBERMATION.VERIFY Event. 3. Using the Monitor perspective, subscribe with no filter so you can see active Applications. If you see the two completed generations of the VERIFY Application (triggered on the Primary and Standby machines), you have successfully enabled ESP High Availability. 4. To revert to the Primary (now acting as the Standby), use the Command Console to issue another changerole command.
ESPD-5.0-AG-01 119 Section–Preventing auto connection to the Standby
Preventing auto connection to the Standby
When the Primary fails over in an ESP High Availability installation, by default ESP Desktop Client will automatically connect to the Standby. ESP Desktop Client notifies you of the switch from the Primary to Standby through a message in its Console View; otherwise, the switch is transparent. You can set an option that allows you to connect to a different ESP Server when the Primary fails. This feature is useful if, for example, you are using manual failback and want to switch to a specific server.
To prevent auto connection to the Standby 1. In the Connections view, right-click the Primary connection and select Connect. The Connect to ESP dialog appears. 2. Select the Prevent auto-connect on failover option. Tip: If the option isn’t visible, click Details. 3. To connect to a different server, enter the address and port number for that server. 4. Enter the password and click OK.
120 ESPD-5.0-AG-01 Monitoring SNMP Messages
You can use the SNMP Message Viewer to view SNMP messages regarding ESP Server, ESP Agents, ESP High Availability, and Alerts. This chapter contains the following topics: • About SNMP messages • Interpreting SNMP messages • Changing the SNMP Manager settings • Using third-party SNMP Managers • Enabling SNMP messages from ESP System Agents • Receiving SNMP messages • Stopping the SNMP trap receiver • Working with the SNMP Message Viewer
ESPD-5.0-AG-01 121 Section–About SNMP messages
About SNMP messages
ESP Server and SNMP-enabled ESP Agents use SNMP messages to notify users of their activity. These messages can inform you of server startups and shutdowns, ESP Agent inactivity or shutdown, and ESP High Availability messages. To handle SNMP messages, you can configure the ESP Server default SNMP Message Viewer or a different SNMP Manager. ESP Server sends an SNMP trap to the SNMP Message Viewer or SNMP Manager you configured • Each time ESP Server starts or stops. • Each time an ESP Agent starts or stops. • When the Standby reaches the maximum number of consecutive, unsuccessful polling attempts in an ESP High Availability-enabled configuration, indicating a possible problem with ESP Server. ESP Server can also generate user-defined SNMPmessages. For example, when a Cybermation ESP job meets predefined criteria (such as the job starting, ending or ending with a specific completion code), ESP Server can send an SNMP message to the default SNMP Message Viewer or any SNMP Manager. Note: If you are configuring the ESP High Availability Option, Cybermation recommends you configure SNMP. If you are using a third-party SNMP Manager, you can import a Management Information Base (MIB) description file that defines the format the SNMP Manager uses.
Interpreting SNMP messages
The SNMP Message Viewer displays information in the following fields: • Host Name • Parameter 2 •Host IP Address • Parameter 3 • Time Stamp • Parameter 4 • Specific • Parameter 5 • Parameter 1
Host Name
Host Name displays the host name of the machine where the Cybermation ESP product is installed.
122 ESPD-5.0-AG-01 Chapter 8–Monitoring SNMP Messages
Host IP Address
Host IP Address displays the IP address of the machine where the Cybermation ESP product is installed.
Time Stamp
Time Stamp displays the date and time the SNMP Message Viewer captured the message.
Specific
Specific indicates the type of SNMP message. 2 generally indicates a startup message. In an ESP High Availability installation, 2 can indicate a stage 2 failure. 4 generally indicates a shutdown message or ESP Agent inactivity. In an ESP High Availability installation, 4 can indicate a stage 1 failure or an ESP Server role change.
Parameter 1
Parameter 1 indicates the Cybermation product name.
Parameter 2
Parameter 2 indicates the Cybermation product version and build number.
Parameter 3
Parameter 3 can indicate the following: • ESP Server ID of the server that started, shutdown, or changed role • ESP Agent name that started, shutdown or is inactive
Parameter 4
Parameter 4 indicates the IP address of the machine where the SNMP Manager is installed and the port number the machine uses to receive SNMP messages.
ESPD-5.0-AG-01 123 Section–Changing the SNMP Manager settings
Parameter 5
Parameter 5 can indicate the following: • Primary, Standby, or Standalone indicates the startup of ESP Server and its role. • Stopped indicates ESP Server has shut down. • Started, Shutdown, or Inactive indicates the state of an ESP Agent. • Stage 1 Failure or Stage 2 Failed indicates the ESP High Availability detection stage. • Running as Primary or Running as Standby indicates the ESP Server role in an ESP High Availability installation.
Changing the SNMP Manager settings
The ESP Server installation program prompts for SNMP Manager settings. If you did not configure SNMP during installation and want to enable SNMP, you need to update the topology by modifying the SNMP Manager settings. You can configure the settings for third-party SNMP Managers such as HP Openview.
To modify the SNMP Manager settings 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. Right-click the ESP Server node and select Configure Shared Parameters. 5. Click the SNMP tab. 6. Modify the SNMP settings. • Host address of SNMP Manager — The machine the SNMP Manager is installed on. Specify the IP address in dotted-decimal or host name format. • *Input port of SNMP Manager — The port number the SNMP Manager uses to capture SNMP messages. The default is 162. • Community of SNMP Manager — The SNMP Manager you are using determines how messages are sent through your network. Specify public or private. • Also send emails for SNMP messages — Specifies whether you want to receive SNMP messages in email format. The default is false. 7. When you are finished making changes, click OK. 8. Recycle ESP Server.
124 ESPD-5.0-AG-01 Chapter 8–Monitoring SNMP Messages
Using third-party SNMP Managers
If you use a third-party SNMP Manager, for example HP Openview, you can import a Management Information Base (MIB) description file that defines the format the SNMP Manager uses. The name of this file is cybermib.txt. On UNIX, for example, you will find this file in the following directory:
Enabling SNMP messages from ESP System Agents
This section only applies to Release 5 and higher ESP System Agents that have not been configured for SNMP during their installation. If you plan to use an ESP System Agent to relay SNMP data, you must complete the following steps: 1. Enable ESP Agent to send SNMP traps and notifications. a. Connect to ESP Server using ESP Desktop Client. b. Open the Admin perspective. c. Open the Topology view. d. Right-click the ESP Agent you want to configure and select View Properties. e. On the Properties tab, set the SNMP Enabled parameter value to true. f. To save your changes, click Update. 2. Edit the ESP Agent’s agentparm.txt file to provide values for the following parameters: plugins.start_internal_N=management management.snmp.mibfile= management.snmp.host= management.snmp.port= management.snmp.community=
ESPD-5.0-AG-01 125 Section–Receiving SNMP messages
Related documentation For more detailed instructions on changing a parameter to enable ESP Agent to send SNMP traps, see “Modifying ESP Agent configuration parameters” on page 55. For more information about ESP System Agent parameters in the agentparm.txt file • For Release 5 ESP System Agents, see Installing Release 5 ESP System Agents. • For Release 6 ESP System Agents and higher versions, see the ESP System Agent Administrator’s Guide for the respective release.
Receiving SNMP messages
To start receiving SNMP messages 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the SNMP Message Viewer. 4. Click the Start SNMP receiver icon. The Start SNMP message receiver and set port dialog appears. 5. Enter the port number for the SNMP Manager and click OK. Tip: To find the SNMP Manager’s port number, open the Topology view, click the Server Shared Parameters > SNMP tab, and check the Input port of SNMP Manager field.
Stopping the SNMP trap receiver
Stopping the SNMP trap receiver disables the SNMP Message Viewer’s ability to capture SNMP messages. Once stopped, however, you can still view and edit saved messages. To stop the SNMP trap receiver, click the Stop SNMP receiver icon.
126 ESPD-5.0-AG-01 Chapter 8–Monitoring SNMP Messages
Working with the SNMP Message Viewer
Use the icons on the SNMP Message Viewer’s toolbar to save, open, clear and print messages.
Saving SNMP messages You can save SNMP messages and work with them later. You can save the messages in SNMP Message Viewer (.msg) format or in text (.txt) format.
Opening SNMP messages If the SNMP trap receiver is running, you cannot open saved SNMP messages. You must stop the receiver before you can open a file. Using the SNMP Message Viewer, you can only open SNMP message files saved in the .msg format.
Clearing messages from the SNMP Message Viewer You can remove selected messages from the SNMP Message Viewer or clear all messages from it. • To clear selected messages, use the Remove message icon. • To clear all messages, use the Clear table icon. Tip: You can hold down the Shift key to select a range of messages, or hold down the Ctrl key to select several different messages at once.
Printing SNMP messages You can print SNMP messages as they appear on your screen or you can preview and modify the messages in text format before printing them.
To view the SNMP messages in text format before printing them 1. Open the SNMP Message Viewer. 2. Click the Print Preview icon. The messages display in text format. In text format, you can •Use the Ctrl+C shortcut to copy the text from the log. For example, you may want to paste the text into another document. • Edit the displayed text. Any changes will not be saved and do not affect the information in the SNMP message log itself.
ESPD-5.0-AG-01 127 Section–Working with the SNMP Message Viewer
128 ESPD-5.0-AG-01 Working with the Packaged Oracle Database
This chapter provides administrative information related only to the packaged Oracle database. To use a different supported database, consult the documentation provided by the database vendor. This chapter contains the following topics: • About the packaged Oracle database • Changing the database connectivity properties • Implementing a disaster recovery solution • Connecting to a fully replicated Standby database • Changing to a new database • Changing the database name
ESPD-5.0-AG-01 129 Section–About the packaged Oracle database
About the packaged Oracle database
ESP Server is packaged with an Oracle 10g Release 1 database. You can choose to install this database or use another database supported by ESP Server. The packaged database is authenticated, which means it cannot be accessed from database applications that do not comply with its authentication details. When installed, it creates a database named ESP by default. You can specify another name for the database at installation time. The installation program creates the database tables required by ESP Server. Note: If you are using another supported database product, refer to the configuration and administration instructions provided in that product’s documentation. ESP Server uses the database for ESP High Availability, history reporting, and resource management.
ESP High Availability In an ESP High Availability installation, both the Primary and Standby share the same database. If the Primary goes down, the Standby takes over using the same database. If the Primary database goes down, you can connect ESP Server to a different database.
History reporting The database stores workflow information in its tables. You can use the database to inspect the workflow information and produce detailed reports on workflow.
Resource management The database stores the state of all defined resources, such as availability and activation states. ESP Server uses this information to initialize the state of these resources during a warm start.
Related documentation • For more information about ESP High Availability, refer to chapter 7. • For more information about history reporting and resource management, refer to the Cybermation ESP: dSeries User’s Guide.
130 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
Changing the database connectivity properties
You can change the following database connectivity properties using the setdbparm utility.
Property name Description database.maxconnections.allowed The maximum number of database connections (connection pool) available to Espresso. Applications request a connection, perform a database operation, and then return the connection back to the pool. If no connection is available, the application waits until another a connection gets returned to the pool. Oracle can accept up to 300 connections. The default is 50. database.minconnection The number of database connections (connection pool) available to ESP Server when it starts. Based on demand, ESP Server will add new connections to the connection pool, up to the maximum specified by the database.maxconnections.allowed property. jdbc.Driver The name of the JDBC driver ESP Server is using to access the RDBMS jdbc.URL The database URL, for example jdbc:oracle:thin:@
Note: You should coordinate changes to your database with your Oracle administrator.
ESPD-5.0-AG-01 131 Section–Implementing a disaster recovery solution
To change the database connectivity properties 1. Run the setdbparm utility, which is located in the
Implementing a disaster recovery solution
This section describes how to implement a disaster recovery solution for ESP Server running Oracle 10g as its database server. During planned outages or disaster recovery, you can reconnect to a copy of the ESP Server production database and continue processing workflow using a Standby (backup) database.
Data Guard technology overview ESP Server uses the Oracle Data Guard technology to create and maintain an up-to- date transactional copy of its database. By setting up a Standby database, you can ensure your Primary ESP Server database has a backup you can switch to for planned outages or for disaster recovery. Data Guard uses redo and archive logging to keep the Standby database server transactionally consistent with the Primary database server.
Redo and archive logs The Oracle database server manages changes to table data by processing operations (transactions). Operations that change data are written in a data manipulation language (DML), such as SQL. When processing DML operations, the database server generates redo log entries. Redo log entries record changes an operation made to a database. For example, an operation that inserts a new row into a table generates a redo log entry that contains a copy of the changes made to the table. The database server does not commit changes
132 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
to a database until it successfully writes the redo entry to a redo log. As redo logs fill up, the database server archives them, creating archive logs. This redo and archive logging process allows for database recovery in the event of a failure. After the failure has occurred, you can restore an old backup of the database and reapply all the archived logs to update the database to the point just before the failure occurred. Using our previous example, applying the archived redo logs during recovery would reinsert the row lost when the database failed.
Data Guard protection modes
Maximum availability mode ESP Server implements Data Guard using the maximum availability mode. This mode ensures continuous operation and zero data loss. Depending on the Standby database server status, the Primary database server runs in maximum protection mode (zero data loss) or maximum performance mode.
Maximum protection mode If the Standby database server is running, the Primary database server runs in maximum protection (zero data loss) mode. In the maximum protection mode, the Primary database server writes both its own online redo logs and the Standby database server redo logs simultaneously. The Primary database server does not commit its own online redo logs until it receives confirmation that the Standby database server received the redo information. Because redo logs are shipped synchronously on the Primary and Standby database servers, the maximum protection mode guarantees that no data will be lost between the two servers. In the event of a failure on the Primary database server, you can use the Standby database server as a fully up-to-date copy of the Primary database server. If the Standby database server becomes unavailable, redo data cannot be synchronously applied to both the Primary and Standby database servers. To ensure continuous operation, the Primary database server runs in maximum performance mode when the Standby database server becomes unavailable. Note: Guaranteeing zero data loss comes at the price of performance on the Primary database server. Because both the Primary and Standby database servers must successfully write DML operations to redo logs before committing data to the Primary database, the Primary database server incurs some overhead. You can minimize performance overhead by tuning your database and ensuring the network connection between the Primary and Standby database servers can adequately handle the quantity of database changes.
Maximum performance mode If the Standby database server is unavailable, the Primary database server runs in maximum performance mode. In the maximum performance mode, the Primary
ESPD-5.0-AG-01 133 Section–Implementing a disaster recovery solution
database server generates and archives redo logs. A background process ships archived redo logs to the Standby database server. The Standby database server functions in perpetual recovery mode. As new logs arrive, the Standby database server applies the logs to its database, creating a copy of the Primary database server. Because archived redo logs are shipped asynchronously in the background, the maximum performance mode does not affect the Primary database server performance. When the Standby database server comes back online, it synchronizes with the Primary database server by requesting and applying missed archived logs. Once caught up, the Primary database server resumes functioning in maximum protection (zero data loss) mode. Note: In the event of a failure on the Primary database server while the Standby database server is unavailable, redo logs the Primary database server had not yet archived are lost. Depending on the size of the online redo logs and the quantity of transactions the database handles, you may need to recreate a significant number of lost transactions.
ESP Server/Oracle Data Guard implementation requirements To implement a standby database using Oracle Data Guard, you require two identical database servers. The database servers must • Run on the same operating system • Both have Oracle 10g Release 1 installed • Use the same directory file structure To maximize performance, you should have a dedicated network connection between the primary and standby database servers, as shown in the following figure.
134 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
ESPD-5.0-AG-01 135 Section–Implementing a disaster recovery solution
Creating a Standby database
To create a Standby database 1. Follow the procedures to install the packaged Oracle database on your Primary server. 2. Repeat step 1 on your Standby server. During the installation steps, pay attention to the following: • Select Installation Option Select Database Server Only. This option installs Oracle server binaries without an ESP database. • Choose Install Directory Ensure you use the same directory name for the Standby database server as you used for the Primary database server. When you have completed step 2, you should have an ESP database running on the Primary server and the required Oracle server binaries installed on the Standby server. 3. Log in to the Primary database server as the oracle user. 4. Change to the $ORACLE_HOME/cybermation/ESPDG directory. This directory contains all the scripts you require to create a Standby database server. At the prompt type cd $ORACLE_HOME/cybermation/ESPDG 5. Edit the dgvars file, located in the ESPDG directory, for your environment. Edit the bold items in the file and resave it. Refer to the following sample as a guide.
On UNIX ############################################################### # MODIFY THE FOLLOWING VARIABLES FOR YOUR ENVIRONMENT # NOTE: HIGH LEVEL DIRECTORIES MUST EXIST. # The application will create subdirectories under the high level directories as required. # ORACLE_SID of the primary database setenv PRIMARY_SID ETEST44 # ORACLE_HOME directory # This is the high level directory where the Oracle server # binaries were installed on both primary and standby servers
136 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
# NOTE: Oracle must be installed in the same directory on both # primary and standby servers. setenv ORACLE_HOME /usr/local/ora10g/product/10g # High level data file directory setenv DATADIR /usr/local/ora10g/product/10.1.0.3/oradata # High level archive log directory # NOTE: Directory must exist setenv ARCHDIR /usr/local/ora10g/product/10.1.0.3/arch # High level Oracle admin directory # NOTE: Directory must exist setenv ADMINDIR /usr/local/ora10g/product/10.1.0.3/admin # SYS user password setenv SYSPASS cybermation # High level temporary working directory. # NOTE: Directory must exist setenv TEMPDIR /usr/local/ora10g # Primary database server host name or static IP address setenv PRIMARY_HOST jaguar setenv STANDBY_HOST panther # Protection Mode, # Options PROTECTION, AVAILABILITY, or PERFORMANCE # Default is AVAILABILITY setenv PROTECTION_MODE AVAILABILITY
On Windows rem MODIFY THE FOLLOWING VARIABLES FOR YOUR ENVIRONMENT rem NOTE: HIGH LEVEL DIRECTORIES MUST EXIST. rem The application will create subdirectories under the high level directories rem as required. rem ORACLE_SID of the primary database set PRIMARY_SID=ESP rem ORACLE_HOME directory
ESPD-5.0-AG-01 137 Section–Implementing a disaster recovery solution
rem This is the high level directory where the Oracle server rem binaries were installed on both primary and standby servers rem NOTE: Oracle must be installed in the same directory on both rem primary and standby servers. set ORACLE_HOME=d:\ora10g\10.1.0.3 rem High level data file directory set DATADIR=d:\ora10g\10.1.0.3\oradata rem High level Oracle admin directory rem NOTE: Directory must exist set ADMINDIR=d:\ora10g\10.1.0.3\admin rem SYS user password set SYSPASS cybermation rem High level temporary working directory. rem NOTE: Directory must exist set TEMPDIR=d:\ora10g\10.1.0.3 rem Primary database server host name or static IP address set PRIMARY_HOST=primary_server set STANDBY_HOST=standby_server rem Protection Mode, rem Options PROTECTION, AVAILABILITY, or PERFORMANCE rem Default is AVAILABILITY set PROTECTION_MODE=AVAILABILITY
138 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
6. Run the PrimaryESPDGSetup.sh script, on UNIX, or the PrimaryESPDGSetup.cmd script, on Windows, as the Oracle owner. The script references the dgvars script you defined in step 5. • On UNIX type ./PrimaryESPDGSetup.sh • On Windows type PrimaryESPDGSetup.cmd When this script completes, it will have created a Standby copy of your Oracle database in a package zip file. You will find the file in the temporary directory specified in the dgvars file on UNIX or the dgvars.cmd file on Windows. The file name will be
ESPD-5.0-AG-01 139 Section–Implementing a disaster recovery solution
10. Start the Oracle Listener process by issuing the following command: • On UNIX type lsnrctl start • On Windows type net start OracleESPTNSListener The Oracle Listener process manages all connections to the Oracle instance. For ESP Server to connect to the database, the Oracle Listener process must be running. 11. Change into the newly created ESP directory. For example, type cd ESP. 12. Run the StandbyESPDGSetup.sh script, on UNIX, or the StandbyESPDGSetup.cmd script, on Windows, located in that directory. This script performs the required steps to configure and start the Standby database server. • On Unix type ./StandbyESPDGSetup.sh • On Windows type StandbyESPSDGSetup.cmd Note: At this point, your Standby database server is operational and waiting for updates from the Primary database server. 13. Log in to the Primary database server again and complete the Data Guard setup by running the FinishPrimary.sh script from the $ORACLE_HOME/ cybermation/ESPDG directory on UNIX or the FinishPrimary.cmd from the %ORACLE_HOME%/cybermation/ESPDG directory on Windows. This script performs the remaining configuration on the Primary database server and issues a startup. From this point forward, the Primary database server keeps the Standby database server synchronized.
140 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
Connecting to a fully replicated Standby database
Important: If you change the database connection while ESP Server tries to recover from a database failure (standby mode), ensure you connect to a database that fully replicates the database being replaced.
If the Primary (production) database fails, ESP Server goes into standby mode. You can connect to a Standby database using the Command Console.
To connect to a Standby database 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: setjdbcurl theNewJdbcURL theNewJdbcURL is the address where the relational database resides ESP Server connects to the Standby database and restarts.
Example: Connecting to an Oracle database The following example tells ESP Server to connect to the Oracle database named ESP. The database host name is mydbserver and the database port is 1521. The driver type is oracle:thin. setjdbcurl jdbc:oracle:thin:@mydbserver:1521:ESP
Changing to a new database
To change the type of relational database ESP Server uses, you must rerun the ESP Server installation program. However, if you want to retain your data when you change the database type, you must use a relational database migration utility.
To change to an empty database 1. Change the ESP Server start type to cold. 2. Stop ESP Server. 3. Run the ESP Server installation program. When the Select an Installation option appears, select the option to reinstall and preserve your existing configuration.
ESPD-5.0-AG-01 141 Section–Changing the database name
4. The installation program prompts you to make changes to the database configuration. Select Yes to make changes to the database configuration. 5. When prompted for information about the relational database, enter values based on the new relational database. 6. Start ESP Server.
To change to another database and migrate your existing data 1. Stop ESP Server. 2. Run the ESP Server installation program. When the Select an Installation option appears, select the option to reinstall and preserve your existing configuration. 3. You will be asked if you want to make changes to the database configuration. Select Yes to make changes to the database configuration. 4. When prompted for information about the relational database, enter values based on the new relational database. 5. To migrate your existing data, use a relational database migration utility to export data from the old database to the new one. 6. Start ESP Server.
Related topics For information about the ESP Server installation program, see the Installing Cybermation ESP: dSeries guide.
Changing the database name
If you change the name of your relational database, you can reinstall ESP Server and change the name when prompted in the installation program. However, if you want to retain your data when you change the database name, you need to use a relational database migration utility.
To change the name of your database 1. Stop ESP Server. 2. Run the ESP Server installation program. When the Select an Installation option appears, select the option to reinstall and preserve your existing configuration. 3. You will be asked if you want to make changes to the database configuration. Select Yes to make changes to the database configuration. 4. When prompted for information about the relational database, enter the new database name.
142 ESPD-5.0-AG-01 Chapter 9–Working with the Packaged Oracle Database
5. If you want to retain data from the old relational database, use a relational database migration utility to export data from the old database to the new one. 6. Start ESP Server.
ESPD-5.0-AG-01 143 Section–Changing the database name
144 ESPD-5.0-AG-01 Cybermation ESP: dSeries Maintenance Procedures
This chapter provides maintenance procedures for ESP Server, the packaged Oracle database, and ESP Agents. The procedures are grouped into the following sections: • Setting up a housekeeping Application • Packaged Oracle database maintenance • ESP Server maintenance • ESP Agent maintenance
ESPD-5.0-AG-01 145 Section–Setting up a housekeeping Application
Setting up a housekeeping Application
ESP Desktop Client is packaged with a sample Application, named housekeeping, that contains the following jobs: • ORACLE_FULL_BACKUP performs a full backup of the packaged Oracle database in the flash recovery area • CLEANUP removes log files, spool files, and .odb files that accumulate over time • PURGE_COMPLETED clears completed jobs from the ESP Server completed jobs repository If you are working in a UNIX environment, you can modify and schedule this Application to perform routine maintenance of your ESP Server and packaged Oracle database. Note: For Windows environments, use the housekeeping Application as a model and change the job types to Windows.
To use the housekeeping Application 1. Connect to ESP Server using ESP Desktop Client. 2. Use the Define perspective to open the housekeeping Application, located in the ESP Desktop Client
146 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
included with the packaged Oracle database, which may be installed on a separate machine. Run frequency — Enter your schedule criteria. The default is run anyday. Script/command name — Enter the path to the oracle_full_backup utility provided with the packaged Oracle database. User ID — Enter your Oracle user ID. The default is oracle. For more information about the oracle_full_backup utility, see “Creating a routine backup of the ESP Server database” on page 148. • CLEANUP
Agent name — Enter the name of your default ESP Agent installed with ESP Server. Run frequency — Enter your schedule criteria. The default is run anyday. Script/command name — Enter the path to the cleanup utility provided with ESP Server. This utility is located in the
4. To schedule the Application, open the default Date-Time/Manual Event and edit the run frequency. 5. Upload the Application to the server.
ESPD-5.0-AG-01 147 Section–Packaged Oracle database maintenance
Packaged Oracle database maintenance
Related topics The procedures in this section only apply to ESP Server installations that use the packaged Oracle database: • “Setting environment variables” on page 148 • “Starting the relational database” on page 148 • “Stopping the relational database” on page 150 • “Creating a routine backup of the ESP Server database” on page 152 • “Recovering your ESP Server database” on page 152 • “Clearing your ESP Server database” on page 154
Setting environment variables To perform these tasks, you require authorization to the user ID that owns the Oracle 10g server and database instances. Before maintaining the database, you must set the following environment variables. • On UNIX: export ORACLE_HOME={top level oracle binary directory} export PATH=$PATH:$ORACLE_HOME/bin export LD_LIBRARY_PATH=$ORACLE_HOME/lib export ORACLE_SID={Oracle Instance Identifier} • On Windows: set ORACLE_HOME={top level oracle binary directory} set PATH=%PATH%:%ORACLE_HOME%\bin set ORACLE_SID={Oracle Instance Identifier} ORACLE_SID is the Oracle instance name that you specify during installation. The default name for the database is ESP.
Starting the relational database You must start the relational database before you can start ESP Server. The default administrative system ID and password for the ESP Server embedded Oracle 10g database are • ID — sys • Password — cybermation
148 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
The startup sequence is • Start the Oracle Listener process • Start the database instance
Starting the Oracle Listener process The Oracle Listener process manages all connections to the Oracle instance. For ESP Server to connect to the database, the Oracle Listener process must be running. You start the Oracle Listener process from the command line. On a Windows server, you can also start the Oracle Listener process through its Windows service.
To start the Oracle Listener process from the command line 1. Log in as the Oracle user. 2. Change to the bin subdirectory. • On UNIX: cd $ORACLE_HOME/bin • On Windows: cd %ORACLE_HOME%\bin 3. Start the listener. %> lsnrctl start
To start the Oracle Listener process through its Windows service 1. From the Windows Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. Right-click the Oracle
Starting the database instance For a routine startup, you can use the Oracle script dbstart. On a Windows server, you can also start the database instance through its Windows service. If you have problems starting the database with the script or Windows service, start the database manually to determine where the problems are. We recommend the following manual process for starting the database instance.
ESPD-5.0-AG-01 149 Section–Packaged Oracle database maintenance
To start the database instance manually 1. Set your ORACLE_SID environment variable to the instance name of the database you want to start. • On UNIX: ORACLE_SID=instance_name; export ORACLE_SID • On Windows: set ORACLE_SID=instance_name 2. Connect to the database using SQLPlus. sqlplus /nolog 3. At the prompt, type the following commands: SQL> connect id/password@ORACLE_SID as sysdba; SQL> startup; SQL> quit;
To start the database instance through its Windows service 1. From the Windows Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. Right-click the OracleService
Stopping the relational database The shutdown sequence is • Stop the database instance • Stop the Oracle Listener process
Stopping the database instance For a routine shutdown, you can use the Oracle script dbshut. On a Windows server, you can also stop the database instance through its Windows service. If you have problems stopping the database with the script or Windows service, stop the database manually to determine where the problems are. We recommend the following manual process for stopping the database instance.
150 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
To stop the database instance manually 1. Set your ORACLE_SID environment variable to the instance name of the database you want to stop. • On UNIX: ORACLE_SID=instance_name; export ORACLE_SID • On Windows: set ORACLE_SID=instance_name 2. Connect to the database using SQLPlus. sqlplus /nolog 3. At the prompt, type the following commands: SQL> connect id/password@ORACLE_SID as sysdba; SQL> shutdown; SQL> quit;
To stop the database instance through its Windows service 1. From the Windows Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. Right-click the OracleService
Stopping the Oracle Listener process The Oracle Listener process manages all connections to the Oracle instance. You stop the Oracle Listener process from the command line. On a Windows server, you can also stop the Oracle Listener process through its Windows service.
To stop the Oracle Listener process from the command line 1. Log in as the Oracle user. 2. Change to the bin subdirectory. • On UNIX: cd $ORACLE_HOME/bin • On Windows: cd %ORACLE_HOME%\bin
ESPD-5.0-AG-01 151 Section–Packaged Oracle database maintenance
3. Stop the listener. %> lsnrctl stop
To stop the Oracle Listener process through its Windows service 1. From the Windows Control Panel, double-click the Administrative Tools icon. The Administrative Tools dialog appears. 2. Double-click the Services icon. The Services dialog appears. 3. Right-click the Oracle
Creating a routine backup of the ESP Server database To perform a backup, you do not need to take the database offline. During the backup, ESP Server continues to manage your scheduled processes. To back up your ESP Server database including all archived log files, issue the following command as the Oracle user for your installation. • On UNIX: ./$ORACLE_HOME/cybermation/scripts/full_backup.sh • On Windows .\%ORACLE_HOME%\cybermation\scripts\full_backup.cmd The full_backup script stores a full backup of your ESP Server database in the flash recovery area in the following directory: • On UNIX: $ORACLE_HOME/flash_recovery_area/$ORACLE_SID • On Windows: %ORACLE_HOME%\flash_recovery_area\%ORACLE_SID% ORACLE_SID is the Oracle instance name. The default is ESP. Your database control files store a catalog of your backups and their contents. To ensure a successful recovery, you must protect your control files.
Recovering your ESP Server database The database recovery approach and success depends on the severity of the failure and how much data was lost.
152 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
Recovering your ESP Server database involves two processes: • Database restore — Restores the database to the point when it was last backed up • Database recovery — Recovers the database to the point just before the failure occurred by applying archived redo logs generated since the last backup. Using archive redo logs, you can recover the database to the point of failure. Your flash recovery area contains the required full backups and archived logs since the last backup. For a successful recovery of a failed database, ensure you protect your control files. To prevent loss of control files, Oracle maintains redundant copies of your most recent control files. The packaged ESP Server database contains three multiplexed control files that are duplicates of each other in case one becomes corrupt or lost. Usually, you can perform a full restore and recovery of the database to the point of failure. To fully restore and recover your database, issue the following command. • On UNIX: ./$ORACLE_HOME/cybermation/scripts/full_recovery.sh • On Windows: .\%ORACLE_HOME%\cybermation\scripts\full_recovery.cmd Sometimes, however, a full restore and recovery of the database is impossible. In this case, the recovery process uses your most recent backup and all available archived redo logs. Any online transactions that were not committed to disk at the point of failure will be lost. To partially restore and recover your database, issue the following command. • On UNIX: ./$ORACLE_HOME/cybermation/scripts/ partial_recovery_no_redo.sh • On Windows: .\%ORACLE_HOME%\cybermation\scripts\partial_recovery_no_r edo.cmd
ESPD-5.0-AG-01 153 Section–ESP Server maintenance
Clearing your ESP Server database The ESP Server installation program sets up the following database tables to store job history data: • ESP_APPLICATION • ESP_JOB_INDEX • ESP_AS400_JOB • ESP_PEOPLESOFT_JOB • ESP_BDC_JOB • ESP_SAP_JOB • ESP_BWIP_JOB • ESP_SPDA_JOB • ESP_BWPC_JOB • ESP_SPPM_JOB • ESP_FILEMONTR_JOB • ESP_VIRTUAL_JOB • ESP_GENERIC_JOB For a description of these tables, refer to the Cybermation ESP: dSeries User’s Guide. We recommend you archive the information in these tables on a regular basis and then clear the tables. To clear the database tables, use the following SQL statement: DELETE FROM ESP_APPLICATION WHERE END_DATE_TIME < 'Date_Argument';
Important: In the SQL statement, DO NOT specify a date that will impact active workflow.
Note: The database schema uses cascade delete, which sets up dependencies between rows in the tables. Consequently, when you use the single SQL statement above, it clears data from all the database tables that store job-history data.
ESP Server maintenance
Related topics The following maintenance procedures apply to ESP Server: • “Performing an automated cleanup of ESP Server” on page 155 • “Resetting Application generations” on page 155 • “Clearing the ESP Server completed jobs repository” on page 156 • “Archiving server log files” on page 157 • “Clearing console.txt backup files” on page 158 • “Clearing server log files” on page 159 • “Clearing server.log files (UNIX systems only)” on page 161
154 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
Performing an automated cleanup of ESP Server This procedure applies to ESP Server installations using the Oracle packaged database. You can run the cleanup utility to remove the following files and folders that accumulate over time: • Default ESP Agent log files and spool files • ESP Server log files located in the
To perform an automated cleanup of ESP Server Run the cleanup utility, which is located in the
Resetting Application generations As ESP Server processes workflow, Application generations continue to increase. You can reset a single Application generation or all Application generations by issuing the resetgen application command using the Command Console.
To reset Application generations 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console.
ESPD-5.0-AG-01 155 Section–ESP Server maintenance
4. Enter the following command: resetgen application(app_name) app_name is the name of the Application you want to reset, such as application(PAYROLL). Use * to reset all Application generations to 0. ESP Server returns an error if the Application is active (not completed). Complete the Application and re-enter the command. If the Application is complete, ESP Server purges all completed generations and resets the generation count to 0.
Clearing the ESP Server completed jobs repository As ESP Server runs, it collects information about active and completed jobs. Your ESP Server relational database stores this information in two tables: ESP_WSS_APPL and ESP_WSS_JOB. To maintain performance, you must periodically clear these tables. The following describes the options for clearing completed jobs: completedjobs purge [olderthan(schedule_expression)] [application(app_name[.gen_num])]
Keyword Description none ESP Server purges all completed jobs. olderthan Optional. Purges all jobs older than the schedule (schedule_expression) expression. The schedule expression resolves to a single time. For example, the expression "now less 24 hours" resolves to a time 24 hours before the time you issue this command. This command is only active at the time you issue it. If you specify a future time, you purge all completed jobs. Note: If the schedule expression resolves to a day, ESP Server uses the implicit time of midnight. application Optional. Purges all completed jobs or specified (app_name[.gen_num]) generations of the named Application. For example, if you specify 5, you purge the completed jobs in generations 1, 2, 3, 4, and 5 of the named Application. If you use the keyword olderthan with the keyword application, you purge only those completed jobs in the Application generations that meet the schedule criteria. For example, if you specify the Application name VERIFY and a schedule expression of "now less than 24 hours", you purge all completed jobs in all generations of the Application VERIFY that are 24 hours old or older.
156 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
Recommended frequency Clear the ESP Server completed jobs repository after 10,000 jobs have completed.
Example: Clearing the ESP Server completed jobs repository This example purges all applications older than 24 hours. 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: completedjobs purge olderthan(now less 24 hours)
Archiving server log files By default, ESP Server automatically archives the trace and AFM logs. If you run extremely heavy workflow, you might consider changing the default frequency for the automatic archive, or you might want to perform a manual archive. Note: ESP Server creates a new audit log every day. You cannot change this behavior. Log files constantly increase in size because ESP Server continually writes to them. To reduce the amount of information stored in these files, ESP Server performs an automatic archive, or rotation, of all its log files. This automatic-archive process reduces clutter in the active log files by creating a new log file on a frequent basis. ESP Server stores the new file in the
Automatically archiving log files
ESP Server uses the Log rotation frequency parameter to control the automatic-archive frequency of the trace and AFM log files. By default, ESP Server uses "midnight", which means that ESP Server automatically archives all log files every day at midnight. To change the automatic-archive frequency, reset the Log rotation frequency parameter using simple scheduling statements, for example, "12 am monday" or "every 3 hours".
To change the automatic-archive frequency 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view.
ESPD-5.0-AG-01 157 Section–ESP Server maintenance
4. In the tree view, right-click the ESP Server node and select Configuration Parameters > Shared Parameters. 5. In the Log rotation frequency field, enter a new frequency, for example, "every 3 hours". 6. Click OK. 7. Recycle the ESP Server.
Manually archiving active log files The spin command archives the contents of an active trace or AFM log file into a new file.
To archive an active log file 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: logname spin where logname is the type of a valid log file (tracelog or afmlog). For example, if you want to archive the active trace log, enter the following command: tracelog spin
Clearing console.txt backup files If you use the Command Utilities packaged with ESP Server, each console command creates a console.txt backup file that is date- and time-stamped, for example, console.20040919163018.txt. ESP Server stores these console.txt files in the directory you issue the command from. Over time, these files accumulate and you will need to clear them.
To clear the console.txt backup files • On UNIX, at the command prompt, type rm console.*.txt where the asterisk (*) is a timestamp wildcard. • On Windows, delete the console.*.txt files.
158 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
Clearing server log files In addition to archiving log files, you can permanently delete or clear trace or AFM log files. You can set a parameter in ESP Server to automatically clear log files at a specific archive frequency. You can also clear active log files manually using the Command Console.
Automatically clearing log files
ESP Server uses the Clear logs after rotation parameter to control the clearing, or deleting, of server log files. The default for clearing log files is false, which means ESP Server does not delete logs after rotation; ESP Server backs up each log file using the name of the log file and the current time.
To automatically clear log files 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Topology view. 4. In the tree view, right-click the ESP Server node and select Initialization Parameters > Shared Parameters. 5. Set the value of the Clear logs after rotation parameter to true. After a warm start, ESP Server deletes the server log files at the frequency specified by the Log rotation frequency parameter. 6. Click OK. 7. Recycle ESP Server.
Manually clearing log files The purge command clears the contents of the active or archived trace or AFM log file. The following describes the options for manually clearing a log file. logname purge[(archived|all)]
Keyword Description logname Name of the log • tracelog — trace log • afmlog — AFM log
ESPD-5.0-AG-01 159 Section–ESP Server maintenance
Keyword Description purge Clears the active log file purge(archived) Removes the archived log files Note: If you change the log file name after archiving, this command only removes the files archived after the name change. purge(all) Clears the active log file and removes the archived log files Note: If you change the log file name after archiving, this command removes the files archived after the name change.
To clear the active log file 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: logname purge where logname is the type of a valid log file (tracelog or afmlog). For example, if you want to clear the active trace log file, enter the following command: tracelog purge
To clear the archived log files 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: logname purge(archived) where logname is the type of a valid log file (tracelog or afmlog). For example, if you want to clear the archived AFM log file, enter the following command: afmlog purge(archived)
To clear the active log file and its archived log files 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective.
160 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
3. Open the Command Console. 4. Enter the following command: logname purge(all) where logname is the type of a valid log file (tracelog or afmlog). For example, if you want to clear the active AFM log file, enter the following command: afmlog purge(all)
Clearing server.log files (UNIX systems only) Each time you recycle ESP Server, the server backs up its server.log file. Recycling the server routinely causes server.log files to accumulate. You need to clear these files manually.
To clear server.log files 1. Change to your ESP Server installation directory. 2. Change to the MonitorAndStatus directory cd MonitorAndStatus 3. At the command prompt, type rm server.*.log where the asterisk (*) is a timestamp wildcard.
ESP Agent maintenance
Related topics The following maintenance procedures apply to ESP Agents: • “Clearing ESP Agent log files manually” on page 162 • “Configuring ESP Agent to clear spool files automatically” on page 162 • “Clearing UNIX spool files using scripts” on page 163 • “Clearing Windows spool files using the clearspool command” on page 165 • “Clearing Agent nohup files (V2 UNIX Agents only)” on page 165 ESP Agent keeps a set of logs that you must clear periodically to maintain disk space availability. The log files contain records of all messages between ESP Agent and the Cybermation host as well as internal messages. These files are located in the log directory by default and are updated continually while ESP Agent is running. The types and number of logs that are generated depend on the log.level parameter set in the agentparm.txt file.
ESPD-5.0-AG-01 161 Section–ESP Agent maintenance
You can clear the log files automatically or manually.
Clearing ESP Agent log files manually Use the agentmsg control command to manually clear all log files on ESP Agent, both active and archived, with the extension .log. 1. Connect to ESP Server using ESP Desktop Client. 2. Open the Admin perspective. 3. Open the Command Console. 4. Enter the following command: agentmsg control agentname(agentname) clrfiles agentname is the name of the ESP Agent whose log files you want to clear.
Configuring ESP Agent to clear spool files automatically By default, ESP Agent does not clear the spool files. You can configure ESP Agent to automatically clear the spool files regularly by modifying the agentparm.txt file. 1. Enable the spool file cleaner (off by default). runnerplugin.spool.clean.enable=true 2. Specify the file expiration time. ESP Agent deletes spool files that are older than this value. The default is 10D (10 days). runnerplugin.spool.expire=
162 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
3. Specify the sleep interval. At every interval, ESP Agent checks for spool files that meet the expiration time and deletes them. The default is 1D (1 day). runnerplugin.spool.sleep=
Example: Deleting spool files older than 10 days The following ESP Agent parameters configure ESP Agent to check the spool files every 36 hours and delete spool files that are older than 10 days. runnerplugin.spool.clean.enable=true runnerplugin.spool.expire=10D runnerplugin.spool.sleep=36H
Example: Checking spool files when the sleep interval is greater than the file expiration time Given the following parameters, ESP Agent ignores the two hour sleep interval set by runnerplugin.spool.sleep. ESP Agent checks the spool files every 50 minutes and deletes spool files that are older than 50 minutes as specified by runnerplugin.spool.expire. runnerplugin.spool.clean.enable=true runnerplugin.spool.expire=50M runnerplugin.spool.sleep=2H
Clearing UNIX spool files using scripts You can clear UNIX spool files periodically using the clearspool and deldirifempty (delete directory if empty) scripts. 1. Create the clearspool and deldirifempty scripts. 2. Schedule the clearspool script using Cybermation ESP, or run it manually. The clearspool script deletes files that meet certain modification time criteria. If the spool files are completely cleared, the clearspool script calls
ESPD-5.0-AG-01 163 Section–ESP Agent maintenance
deldirifempty. The deldirifempty script deletes empty directories within the spool directory. If you run clearspool from a Telnet session, ensure you switch to the directory containing the spool files. If you used the defaults when installing ESP Agent, the spool directory is called spool. The clearspool script assumes the spool directory is called spool in the current directory. If not, supply the full directory path name in the environment variable SPOOL.
Creating the clearspool and deldirifempty scripts The following are sample scripts. You can have other file maintenance procedures. 1. Create a script called clearspool that contains the following code: #! /bin/ksh if [[ -z $SPOOL ]] then SPOOL=./spool fi find $SPOOL -type f -mtime +n -exec rm {} \; find $SPOOL -depth -type d -exec /bin/ksh /script_path/ deldirifempty {} \;
• mtime n specifies the age of the files to be deleted, where • +n — deletes files last modified more than n days. • n — deletes file last modified exactly n days ago. • -n — deletes files last modified less than n days ago. Note: Put this script in the same directory as the cybAgent binary. Otherwise, specify the full path for SPOOL. You cannot specify a symbolic-linked directory for the SPOOL path. 2. Create the script called deldirifempty that contains the following code: #!/bin/ksh Dir=$(ls -A $1) if [[ -z $Dir ]] then echo "deleting directory $1" rmdir $1 else echo "$1 is not empty" fi
164 ESPD-5.0-AG-01 Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
Example: Deleting files modified yesterday or earlier In the following example, mtime is specified as +1 to delete files that were last modified at least one day ago. The clearspool script then calls the deldirifempty script, which deletes any empty spool subdirectories. #!/bin/ksh if [[ -z $SPOOL ]] then SPOOL=/AgentDirectory/spool fi find $SPOOL –type f –mtime +1 –exec rm {} \; find $SPOOL –depth –type d -exec /bin/ksh /script_path/ deldirifempty {} \; Note: $SPOOL cannot be symbolic-linked directories.
Clearing Windows spool files using the clearspool command You can clear Windows spool files with the clearspool command. Use clearspool in one of two ways: • Schedule clearspool to run periodically in a Cybermation ESP Application •Run clearspool manually by issuing the clearspool command from the Windows command prompt
Running the clearspool command manually 1. Define the ESPAGENTDIR environment variable with the path to the ESP Agent directory. The ESP Agent directory must contain a valid agentparm.txt file. 2. At the command prompt, enter the clearspool command.
Example: Clearing spool files older than five days This command deletes all files older than five days.
clearspool 5
Example: Displaying debugging messages This command deletes all files older than 10 days and displays debugging messages to the command prompt as it runs.
clearspool 10 debug
Clearing Agent nohup files (V2 UNIX Agents only) This procedure applies to Version 2 UNIX Agents. When you use nohup as part of the command to start the V2 Agent, the Agent creates a timestamped nohup file to
ESPD-5.0-AG-01 165 Section–ESP Agent maintenance
back up its console messages. If you recycle the Agents routinely, nohup files will accumulate in the Agent directory. You will need to clear the Agent nohup files manually. Note: In newer versions of the UNIX Agent, the Agent stores the console messages in its log files. When you use nohup as part of the command to start the Agent, the Agent creates one nohup file. However, this nohup is empty, so there is no need to clear it.
To clear UNIX Agent nohup files 1. Change to the Agent directory you want to clear. 2. At the command prompt, type rm nohup.*.out where * is a timestamp wildcard. 3. Repeat steps 1 and 2 for each Agent.
166 ESPD-5.0-AG-01 Command Console Commands
This chapter describes the commands you can enter from the Command Console and how to issue appcmds using the Command Utility. This chapter contains the following topics: • Command definitions and syntax • Issuing appcmd commands using the Command Utility
ESPD-5.0-AG-01 167 Section–Command definitions and syntax
Command definitions and syntax
The Command Console commands are grouped into four categories: ESP Agent commands, log commands, ESP Server commands, and workflow commands.
ESP Agent commands Note: In an ESP High Availability configuration, you can only issue the following commands on the Primary.
Command Description Syntax Related Topics agent Issues an ESP Agent agent • “Clearing ESP Agent control command agentname(agentname) receiver messages” on flush|restart|quiesce page 59 • “Resuming message sending to an ESP Agent” on page 59 • “Holding ESP Agent receiver messages” on page 59 agentmsg control Issues an ESP Agent agentmsg control •“Shutting down an ESP control command agentname(agentname) Agent” on page 58 shutdown|refresh|clrfiles • “Clearing ESP Agent receiver messages” on page 59 • “Clearing ESP Agent log files manually” on page 162
In the syntax column • Italic indicates a variable. • A vertical bar "|" indicates that you must specify either the keyword to the left of the bar or the keyword to the right of the bar.
Log commands
Command Description Syntax Related Topics afmlog filterid Applies filter ID numbers afmlog filterid(nnn) “Applying temporary tracelog to the ESP Server active filter IDs” on page 99 AFM log afmlog purge Clears the ESP Server afmlog “Clearing server log files” on AFM logs purge[(archived|all)] page 159 afmlog spin Archives the ESP Server afmlog spin “Archiving server log files” on active AFM log page 157
168 ESPD-5.0-AG-01 Chapter 11–Command Console Commands
Command Description Syntax Related Topics auditlog export Creates an audit log in auditlog export “Creating an audit log report” Comma Separated Values path(directory_path) on page 98 (CSF) format and a report name(name) in html format [startdate(yyyyMMdd)] [enddate(yyyyMMdd)] display afmlog Displays the location and display afmlog file name of the ESP Server AFM log display auditlog Displays the location and display auditlog file name of the ESP Server audit log display tracelog Displays the location and display tracelog file name of the ESP Server trace log tracelog filterid Applies filter ID numbers tracelog filterid(nnn) “Applying temporary tracelog to the ESP Server active filter IDs” on page 99 trace log tracelog purge Clears the ESP Server tracelog “Clearing server log files” on trace log purge[(archived|all)] page 159 tracelog spin Archives the ESP Server tracelog spin “Archiving server log files” on active trace log page 157
In the syntax column • Italic indicates a variable. • A vertical bar "|" indicates that you must specify either the keyword to the left of the bar or the keyword to the right of the bar. • A pair of square brackets "[ ]" enclosing a keyword indicates that the keyword is optional.
ESPD-5.0-AG-01 169 Section–Command definitions and syntax
ESP Server commands
Command Description Syntax Related Topics about Shows the ESP Server version about “Viewing a list of users and build number, as well as a connected to the server” on list of users connected to ESP page 12 Server changerole Changes the ESP Server ESP changerole “Switching Primary and High Availability role Standby roles” on page 112 countlist Lists the total number of each countlist “Viewing a list of artifacts in the ESP artifact type in your system. system” on page 26 ESP artifact types are Agents, Alerts, Applications, Calendars, Events, Forecasts, Groups, JavaScripts, Resources, and Users. licensestatus Displays the total number of licensestatus “Viewing your license status” on licenses available, the number of page 26 licenses in use, and the temporary licenses’ expiry date memcheck Displays the total free memory memcheck “Checking the server memory and maximum heap size usage” on page 25 setjdbcurl Tells the ESP Server to connect setjdbcurl “Connecting to a fully replicated to a new relational database. Use theNewJdbcURL Standby database” on page 141 this command if you want ESP Server to connect to a fully replicated standby database (for example, in a Data Guard configuration). stop Stops the ESP Server stop “Stopping ESP Server using the Command Console” on page 21
In the syntax column, italic indicates a variable.
170 ESPD-5.0-AG-01 Chapter 11–Command Console Commands
workflow commands Note: In an ESP High Availability configuration, you can only issue the following commands on the Primary.
Command Description Syntax Related Topics completedjobs Purges completed jobs completedjobs purge “Clearing the ESP Server purge • All jobs [olderthan(schedule_expres completed jobs repository” on •Those job older than sion)] page 156 a scheduled time [application(app_name.[ge •A particular n_num])] generation and its predecessors display Displays information display workloadobject about a job running in workloadobject(applname ESP Server .gen. wobname.qualifier) resetgen application Purges all completed resetgen “Resetting Application generations of the application(*|applname) generations” on page 155 specified application and resets the generation number to 0
In the syntax column • Italic indicates a variable. • A vertical bar "|" indicates that you must specify either the keyword to the left of the bar or the keyword to the right of the bar. • A pair of square brackets "[ ]" enclosing a keyword indicates that the keyword is optional.
Issuing appcmd commands using the Command Utility
You can use the Command Utility to issue appcmd commands one at a time or as multiple commands in a single statement. Note: The Command Utility is a separate, stand-alone utility that is not related to the ESP Desktop Client’s Admin perspective.
ESPD-5.0-AG-01 171 Section–Issuing appcmd commands using the Command Utility
Syntax Note: On Windows, replace appcmd.sh with appcmd.bat. appcmd.sh host port username password [file to execute] [Wait before close] Note: You must write this statement on a single line. On UNIX, the command is case sensitive. The following table defines the parameter values you must specify. Value Definition host The ESP Server IP address or DNS name port The ESP Server console port. The default value is 7506. username Name of the user issuing the appcmd command password Password of the user issuing the appcmd command file to File containing the appcmd commands execute Wait before Specifies whether you want the system to wait for each appcmd close command to complete before the next one is sent • T — Command Utility will wait for each appcmd to complete (default). • F — Command Utility will exit before receiving a response to each appcmd command.
Issuing appcmd commands interactively You require an active session to carry out this procedure. 1. From the command prompt, enter the following on one line, substituting values for host, port, username, and password: Note: On Windows, replace appcmd.sh with appcmd.bat. appcmd.sh host port username password
2. Press Enter. If your network connection is established, the command prompt changes to the name of the server, for example, Manager: MANAGER> 3. At the prompt, enter the appcmd command, for example, about. about
172 ESPD-5.0-AG-01 Chapter 11–Command Console Commands
4. Once you finish issuing appcmd commands, type @exit and press Enter. Your system disconnects from the server and returns to the command prompt.
Example The following example shows the syntax to start the Command Utility in interactive mode on a host called myesp. This host uses the default console port of 7506 for the ESP Server.
UNIX appcmd.sh myEspresso 7506 Admin admin
Windows appcmd.bat myEspresso 7506 Admin admin
Issuing appcmd commands in batch mode You can write a text file that has multiple appcmd commands in it. When you run the Command Utility to issue the appcmd commands, the Command Utility iterates over each appcmd command in the file, sending each one to the server. Specify a command file for the file you want to execute using one line for each command. The command file is a text file that contains the appcmd commands you wish to run.
Example: Using batch mode The following example shows the syntax to start the Command Utility in batch mode on a host called myEspresso. This host uses the default console port of 7506 for the ESP Server. Your file purgelog.txt contains commands to purge the trace log and AFM log.
UNIX appcmd.sh myEspresso 7506 Admin admin purgelog.txt
Windows appcmd.bat myEspresso 7506 Admin admin purgelog.txt Here is the content of your purgelog.txt file: tracelog purge(all) afmlog purge(all)
ESPD-5.0-AG-01 173 Section–Issuing appcmd commands using the Command Utility
174 ESPD-5.0-AG-01 Integrating Cybermation ESP: dSeries Servers
This chapter covers the procedures for integrating two Cybermation ESP: dSeries Servers. It contains the following topics: • Integrating your ESP Servers • Verifying your integration
ESPD-5.0-AG-01 175 Section–Integrating your ESP Servers
Integrating your ESP Servers
ESP Server is packaged with a default ESP Agent, which you use to route information between two Cybermation ESP: dSeries Servers. You can use either of the default ESP Agents as the router. Before you begin your setup, identify which default ESP Agent you are going to use. In the following diagram, and in the example used in this section, the ESP Server1 default ESP Agent is used to route data between the two ESP Servers. As you work through the steps in this chapter, refer to the Integrating ESP Servers diagram diagram below.
Integrating ESP Servers diagram
Information you need
ESP Server2 Collect the following information about your ESP Server2 system.
Information Required Default Value Value Used Manager name MANAGER2 IP address of the machine where — ESP Server is installed Port number through which the 7507 Manager component receives requests
This information is in the ESP Server topology. You need this information to update the default ESP Agent for ESP Server1.
176 ESPD-5.0-AG-01 Chapter 12–Integrating Cybermation ESP: dSeries Servers
Default ESP Agent Collect the following information about the ESP Server1 default ESP Agent. Information Required Value Used ESP Agent name (default name is AGENT) ESP Agent type (for example, UNIX) IP address of the machine where ESP Agent is installed Port number on which ESP Agent communicates with ESP Server Encryption key
You need this information to define the ESP Server1 default ESP Agent in the topology for ESP Server2.
Setup tasks This section describes the high level tasks you complete to integrate your two ESP Servers. To set up communication between your two ESP Servers, complete two tasks: 1. Update the ESP Server1 default ESP Agent to communicate with ESP Server2. 2. Define the ESP Server1 default ESP Agent in the ESP Server2 topology.
Update the ESP Server1 default ESP Agent to communicate with ESP Server2 You need to update the ESP Server1 default ESP Agent parameter file so the ESP Agent can communicate with ESP Server2. You use the information you collected for ESP Server 2.
To update the ESP Server1 default ESP Agent to communicate with ESP Server2 Note: These steps assume you are using the ESP Server1 default ESP Agent. 1. Open the agentparm.txt for the ESP Server1 default ESP Agent. The default location for the file is
ESPD-5.0-AG-01 177 Section–Integrating your ESP Servers
2. Refer to the information you collected for “ESP Server2” on page 176. Under the Communications section of the agentparm.txt file, make changes to the following three parameters: • communication.managerid_2=manager2I Replace manager2I with the Manager name. • communication.manageraddress_2=manager2A Replace manager2A with the IP address of the machine on which ESP Server2 is installed. • communication.managerport_2=manager2P Replace manager2P with the Manager port number for ESP Server2. 3. For all three parameters, remove the comment character (#) at the beginning of the line to activate these lines. 4. Save and close the file. 5. Restart ESP Server1 default ESP Agent. The following is an example of the agentparm.txt file. The bold text in the example defines the ESP Server2 parameters. The values shown correspond to the values shown in the “Integrating ESP Servers diagram” on page 176.
agentname=AGENT # # Communications communication.managerid_1=MANAGER communication.manageraddress_1=CYBER1 communication.managerport_1=7507 #communication.monitorobject_1=AGENT/AGENTMON1.0/MAIN
communication.managerid_2=MANAGER2 communication.manageraddress_2=CYBER2 communication.managerport_2=7507 #communication.monitorobject_2=AGENT/AGENTMON2.0/MAIN ... communication.inputport=7520 communication.prefixlevel=2 ... security.cryptkey=0x313233343563738
178 ESPD-5.0-AG-01 Chapter 12–Integrating Cybermation ESP: dSeries Servers
Define the ESP Server1 default ESP Agent in ESP Server2 topology You need to define the ESP Server1 default ESP Agent in the ESP Server2 topology so ESP Server2 can communicate with ESP Agent. The ESP Server1 default ESP Agent was defined in the ESP Server1 topology during the ESP Server1 installation. How you complete this task will depend on the naming of the default ESP Agents. Refer to Scenarios 1 or 2 below for the appropriate steps to follow.
Scenario 1: The two default ESP Agents have the same name It is likely that the default ESP Agents for your two ESP Servers will have the same name. If your ESP Server2 default ESP Agent has the same name as the ESP_ Server_1 default ESP Agent, you need to do the following: 1. Change the name of the ESP Server2 default ESP Agent in the ESP Server2 topology. 2. Change the ESP Agent parameter file of the ESP Server2 default ESP Agent to reflect the new name. 3. Update all Applications that use the ESP Server2 default ESP Agent to reflect the new ESP Agent name. 4. Add the ESP Server1 default ESP Agent to the ESP Server2 topology using the ESP Desktop Client Admin perspective. Refer to the information you collected for the “Default ESP Agent” on page 177. Make sure the parameter values for the new ESP Server2 ESP Agent match those defined for the ESP Server1 default ESP Agent.
Scenario 2: The two default ESP Agents have different names If the ESP Server1 default ESP Agent has a different name than the ESP Server2 ESP Agent, then you simply need to add the ESP Server1 default ESP Agent to the ESP Server2 topology. Refer to the information you collected for the “Default ESP Agent” on page 177. Add the ESP Server1 default ESP Agent to the ESP Server2 topology using ESP Desktop Client’s Admin perspective. Make sure the parameter values for the new ESP Server2 ESP Agent match those defined for the ESP Server1 default ESP Agent.
ESPD-5.0-AG-01 179 Section–Verifying your integration
Verifying your integration
To verify that your ESP Server1 and ESP Server2 environments are set up correctly, complete these steps: 1. Create a home Application (APPL1) on one ESP Server system and a distant Application (APPL2) on the other. 2. In your distant Application, define an External Other Scheduler job. 3. Create and trigger Events for both Applications (APPL1 and APPL2). Note: We recommend you create and trigger the Event for the distant Application first. 4. Monitor the jobs running in the distant Application. In the following example, the External Other Scheduler job is defined in the distant Application using ESP Server2. ESP Server1 runs the home Application to submit job B.
Note: This section chapter only provides the procedural steps for defining an External Other Scheduler job. For other procedures required to verify the setup (steps 1, 3, and 4), refer to the Getting Started with Cybermation ESP: dSeries guide.
Define an External Other Scheduler job 1. Use the ESP Desktop Client Define perspective to open an Application. 2. In the Workflow Objects tree, select External-Other Scheduler. 3. Place an External-Other Scheduler icon onto the workspace. 4. Right-click the job icon and select Edit. 5. On the Basic tab, enter the Job name and qualifier. The name and qualifier you assign to your External job must be the same as the name and qualifier of the job in the home Application.
180 ESPD-5.0-AG-01 Chapter 12–Integrating Cybermation ESP: dSeries Servers
6. Complete the following fields: • Specify External Scheduler Name — Enter the name of the other scheduler. This scheduler is running the home Application that submits the job which the External job you are defining depends on. • Specify Agent Name — Enter the name of the Espresso default ESP Agent that you are using to route information between the schedulers. • Specify Application Name — (Optional) To override the default, specify the name of the home Application that submits the job. • Specify Scheduled Parameter — (Optional) To override the default, specify the scheduled time of the Event that submits the job, or the trigger time for non- scheduled Events. 7. Complete the details on the other tabs, as required, and click OK.
ESPD-5.0-AG-01 181 Section–Verifying your integration
182 ESPD-5.0-AG-01 Oracle Administration Primer
This appendix is intended to help you gain some practical knowledge for administering the Oracle 10g server and the ESP Server database. For more in depth explanations of Oracle technology, consult your Oracle documentation. This appendix contains the following topics: • Oracle 10g for ESP Server overview • Oracle server directory structure • Oracle network components • Database initialization files • Oracle database instances (SID) • Database objects • Data backup and restore • Common administrative commands • Useful queries For more information about the Oracle database, consult your Oracle documentation.
ESPD-5.0-AG-01 183 Section–Oracle 10g for ESP Server overview
Oracle 10g for ESP Server overview
The Oracle server is composed of • Oracle server binaries • Oracle network components • Database initialization files • One or more Oracle instances or databases (SIDs) each containing • Tablespaces and datafiles • Two or more control files • Two or more redo log files • Optional archive log files The following diagram depicts a typical Oracle server environment and its component parts:
184 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
The following table shows the location and size of each component.
Component Details Location Size (MB) Oracle 10g Server {ORACLE_HOME} Initialization Files init{SID}.ora {ORACLE_HOME}/dbs < 0.1 spfile{SID}.ora Tablespaces and Datafiles SYSTEM {ORACLE_HOME}/oradata/system0x.dbf 390 SYSAUX {ORACLE_HOME}/oradata/sysaux0x.dbf 100 ESP_DATA {ORACLE_HOME}/oradata/espdata0x.dbf 100 ESP_INDEX {ORACLE_HOME}/oradata/espindex0x.dbf 50 ESP_HIST {ORACLE_HOME}/oradata/esphist0x.dbf 100 ESP_HISTX {ORACLE_HOME}/oradata/esphistx0x.dbf 50 EST_TEMP {ORACLE_HOME}/oradata/esptemp01.dbf 100 ESP_UNDO {ORACLE_HOME}/oradata/espundo01.dbf 100 Control Files control01.ctl {ORACLE_HOME}/oradata 3 control02.ctl {ORACLE_HOME}/oradata 3 control03.ctl {ORACLE_HOME}/oradata 3 Redo Logs {ORACLE_HOME}/oradata 50 {ORACLE_HOME}/oradata 50 {ORACLE_HOME}/oradata 50 Archived Logs and Database Backups {ORACLE_HOME}/flashback_recovery_area 0
Oracle server directory structure
A typical Oracle server installation contains the following directory structure. Directory Content \assistants configuration Assistants \bin binaries for all products \ctx interMedia Text cartridge \dbs initsid.ora, lksid \install install related files \lib Oracle product libraries \jlib Java classes \dd Spatial cartridge \mlx Xerox Stemmer (for interMedia Text cartridge) \network Net8 \nlsrtl NLS run-time loadable data \ocommon common files for all products \odg data gatherer \opsm Parallel Server Manager Components
ESPD-5.0-AG-01 185 Section–Oracle network components
Directory Content \oracore core libraries \ord data cartridges \otrace Oracle TRACE \plsql PL/SQL \precomp precompilers \rdbms server files and libraries required for the database \xlax SLAX parser \sqlplus SQL*Plus
The server files do not include any databases. The Oracle server requires the server files to manage an Oracle instance name (SID). The environment variable ORACLE_HOME defines the top level location of the directory structure. For an Oracle server running in a UNIX environment, you must set the following environment variables, preferably in the Oracle user’s profile: export ORACLE_HOME={top level oracle binary directory} export PATH=$PATH:$ORACLE_HOME/bin export LD_LIBRARY_PATH=$ORACLE_HOME/lib export ORACLE_SID={Oracle Instance Identifier} For an Oracle server running in a Windows environment, you must set the following environment variables, preferably in the Oracle user’s profile: set ORACLE_HOME={top level oracle binary directory} set PATH=%PATH%:%ORACLE_HOME%\bin set ORACLE_SID={Oracle Instance Identifier}
Oracle network components
Oracle’s Listener process Oracle’s Listener process facilitates communication to an Oracle instance using Oracle’s TNS network protocol. The listener accepts Oracle client connections and forwards them to the database server. The listener is a separate process, which starts independently of the Oracle instance. Upon startup, the listener reads a configuration file (listener.ora), which defines the Oracle database instances it listens for. The following is a sample listener.ora file: # LISTENER.ORA Network Configuration File: $ORACLE_HOME/network/admin/listener.ora # Generated by Oracle configuration tools.
LISTENER = (DESCRIPTION_LIST =
186 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = yourhostname)(PORT = 1521)) ) (ADDRESS_LIST = (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC)) ) ) )
SID_LIST_LISTENER = (SID_LIST = (SID_DESC = (SID_NAME = PLSExtProc) (ORACLE_HOME = /home/oracle/product/10.1.0.3) (PROGRAM = extproc) ) (SID_DESC = (GLOBAL_DBNAME = ESPRESSO) (ORACLE_HOME =/home/oracle/product/10.1.0.3) (SID_NAME = ESPRESSO) ) )
In the above example, SID_DESC identifies an Oracle instance name (SID) and its related ORACLE_HOME. The listener process listens and forwards client requests to the Oracle database instance. The default listening port is 1521. For further details on the listener.ora file and the listener process, refer to your Oracle documentation.
Client communication and configuration files Oracle client applications communicate with the Oracle instance via the TNS network protocol. This protocol is typically implemented in two ways: • Full client (OCI) • Thin client (JAVA, jdbc) A full client, typically non-JAVA, requires the client libraries to communicate with the database. The size of the libraries varies from 60MB to 600MB, with the latter including all the system administration tools. Oracle’s Thin Client is a lightweight implementation of the TNS protocol packaged in a small java archive (jar file). The Thin Client does not require the full installation of the client libraries. Client applications require two configuration files to communicate with the database: tnsnames.ora and sqlnet.ora. The tnsnames.ora file contains definitions and aliases to all the Oracle instances the client can access, such as host name, instance
ESPD-5.0-AG-01 187 Section–Oracle network components
name (SID), and port. The sqlnet.ora file stores system-wide defaults, such as time-out values, tracing preferences, and global domain names. The tnsnames.ora file requires one entry for each database instance the client needs to connect to. An entry in the tnsnames.ora file has the following format:
ESPRESSO = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = yourhostname)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = ESPRESSO) ) )
# SQLNET.ORA Network Configuration File: /home/oracle/procut/10.1.0.3/network/admin/tnsnames.ora # Generated by Oracle configuration tools. AUTOMATIC_IPC = ON TRACE_LEVEL_CLIENT = OFF names.directory_path = (TNSNAMES) NAMES.DEFAULT_DOMAIN = world
188 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
NAME.DEFAULT_ZONE = world names.default_domain=world
Database initialization files
Every Oracle instance requires an initialization file to start. The initialization file is typically located in the following directory: • UNIX — $ORACLE_HOME/dbs • Windows — %ORACLE_HOME%\dbs The initialization file takes the format of init
Parameter Value pga_aggregate_target 199229440 processes 300 db_recovery_file_dest_size 8589934592 db_recovery_file_dest {ORACLE_BASE}/flash_recovery_area background_dump_dest {ORACLE_BASE}/admin/{DB_UNIQUE_NAME}/bdump core_dump_dest {ORACLE_BASE}/admin/{DB_UNIQUE_NAME}/cdump user_dump_dest {ORACLE_BASE}/admin/{DB_UNIQUE_NAME}/udump job_queue_processes 10 dispatchers (PROTOCOL=TCP) (SERVICE={SID}XDB) open_cursors 900 db_block_size 8192 undo_tablespace ESP_UNDO log_archive_format ="%t_%s_%r.dbf remote_login_passwordfile EXCLUSIVE
ESPD-5.0-AG-01 189 Section–Oracle database instances (SID)
Parameter Value undo_management AUTO db_file_multiblock_read_count 16 shared_pool_size 155189248 large_pool_size 4194304 sga_target 599785472 java_pool_size 4194304 db_cache_size 432013312 compatible 10.1.0.2.0
You can find a detailed list and description of all parameters in your Oracle documentation.
Oracle database instances (SID)
An Oracle database is often referred to as an Oracle instance or SID. An Oracle database server manages one or more databases or instances. Each instance is an independent entity, only sharing runtime files with other instances. Each instance has its own server processes, memory requirements, and file structure. An instance has logical and physical structures (tablespaces and datafiles).
Server components Besides initialization files, an instance has several key components including the following: • Tablespaces • Datafiles • Control files • Undo segments • Redo logs
Tablespaces and datafiles Tablespaces typically separate data along some logical definition. A typical ESP Server installation of the Oracle database contains the following default tablespaces. You can add additional application-specific tablespaces at any time. Tablespace Name Contents SYSTEM Reserved for system objects (REQUIRED) ESP_UNDO Undo Segments (REQUIRED) ESP_TEMP Temporary storage used for sorting operations on large result sets (REQUIRED)
190 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
Tablespace Name Contents ESP_DATA Default tablespace for operational data structures required by ESP Server ESP_INDEX Tablespace for associated indexes of tables created in the ESP_DATA tablespace ESP_HIST Default tablespace for ESP Server historical data used for reporting purposes ESP_HISTX Tablespace for the associated indexes of tables created in the ESP_HIST tablespace
Tablespaces are represented physically by one or more datafiles. When you create a tablespace, you also define an associated datafile. Consider the following statement: CREATE TABLESPACE "ESP_DATA" DATAFILE '/usr/local/ora10g/product/10.1.0.3/oradata/ETEST44/ espdata01.dbf' SIZE 256M REUSE AUTOEXTEND ON MAXSIZE 8192M LOGGING ONLINE PERMANENT EXTENT MANAGEMENT LOCAL UNIFORM SIZE 500K SEGMENT SPACE MANAGEMENT AUTO; The above statement creates an ESP Server tablespace named ESP_DATA, with one physical datafile (espdata01.dbf) of 256M. Allocations within the datafile are in 500K increments. Once you create the tablespace, you can create objects (such as tables and indexes) within that tablespace, where space is allocated in units called extents. You can add additional datafiles when you require more space. In the above example, the datafile cannot exceed 8GB. To accommodate new growth, you must add a new datafile to the ESP_DATA tablespace. For example, the following statement adds a new datafile called espdata02.dbf of 256M: alter tablespace ESP_DATA add datafile usr/local/ora10g/product/ 10.1.0.3/oradata/ETEST44/espdata02.dbf' size 256M autoextend on maxsize 8192MB;
Control files The control files contain entries that specify the database’s physical structure: database name, path names of datafiles and redo log files, and creation timestamps. Control files, like redo logs, are typically distributed across physical drives to eliminate the possibility of loss or failure.
ESPD-5.0-AG-01 191 Section–Oracle database instances (SID)
Undo segments The Oracle server uses undo tablespaces or segments to rollback uncommitted transactions in the event of a server or application issue. Undo segments contain a copy of data prior to any changes made to the data by a database transaction. In the event of a transaction rollback, the server copies the original data from undo segments back to the original table. The Oracle server automatically manages undo segments, which grow to accommodate database activity. As you would for other Oracle tablespaces, monitor undo tablespaces file size and ensure there is enough physical disk available for growth.
Redo logs By default, the installation procedure creates three redo logs. Redo logs are cyclical data structures used to store transactions, prior to committing them to the actual tables. Redo logs are a critical component in Oracle’s backup and recovery strategy. As redo logs fill, the Oracle server archives them to disk. You can later use these archive redo logs to recover a damaged database. By applying (or replaying) the archived redo logs, you can restore the database to the point just before a failure occurred. Note: Loss of control files can result in an unrecoverable database instance. For more information on Oracle backup and recovery, see “Implementing a disaster recovery solution” on page 132.
Database storage Database storage is organized in data blocks, extents, and segments.
Blocks The smallest logical unit is the data block. One data block corresponds to a specific number of bytes of physical database space on disk. Data blocks are usually allocated in multiples of 4K. The size depends on the underlying operating system block size, usually 4K. Larger block sizes (8K, 16K, 32K) are reserved for data warehouse applications where the server retrieves large amounts of data from the database in one session.
Extents The next level of logical storage is the extent. An extent is a specific number of contiguous data blocks allocated from only one datafile. Extent management is an expensive database operation in terms of performance. The number of extents allocated at one time must be large enough to accommodate the volume of data the application creates. When creating database objects (such as tables and indexes), you can specify the size of an allocated extent.
192 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
Segments The next level of logical storage is the segment. A segment is a set of extents allocated for a specific logical data structure. The same tablespace stores all of a segment’s extents.
Database objects
Schemas A schema is a collection of logical structures of data or schema objects, such as tables, indexes, triggers, and stored procedures. A schema is owned by a database user and has the same name as that user. In Oracle, each user owns a single schema, although you can grant that user privileges to read or modify data in other schemas. Schemas can span multiple tablespaces, allowing for the data organization along both logical lines and physical distribution across datafiles for enhanced performance and fault tolerance. The ESP Server schema spans four tablespaces: ESP_DATA, ESP_INDEX, ESP_HIST, and ESP_HISTX. The following diagram illustrates how a user’s schema can span multiple tablespaces and datafiles.
ESPD-5.0-AG-01 193 Section–Data backup and restore
In the above diagram, USER1’s schema contains objects that span multiple tablespaces (USERTABS, USERINDX, REPORTINDX). USER1 may chose to distribute its database objects across several tablespaces for both logical organization and additional performance throughput. You can improve throughput by distributing objects across multiple tablespaces, reducing contention against one physical file. Although you can distribute database objects across multiple tablespaces, any single object can only reside in one tablespace. For example, tables cannot span multiple tablespaces.
Data backup and restore
This section describes the default backup policies included with the packaged database. Oracle 10g for ESP Server takes advantage of some key features of Oracle’s Recovery Manager (RMAN) to perform routine backup and recovery operations. You can customize RMAN to take advantage of your organization’s backup policies.
The flash recovery area The packaged Oracle 10g server manages a portion of your file system called the flash recovery area. Oracle uses the flash recovery area to store archived redo logs and database backups. Archived redo logs store transactions committed since the last backup. By applying archived redo logs generated since the last backup, you can recover the database to the point of failure. By default, the flash recovery area for your ESP Server database instance is located in the following directory:
UNIX $ORACLE_HOME/flash_recovery_area/$ORACLE_SID
Windows %ORACLE_HOME%\flash_recovery_area\%ORACLE_SID% ORACLE_SID is the Oracle instance name. The default is ESP. Oracle creates subdirectories daily to store the new archive logs and backup files.
Retention policy Oracle uses a retention policy to manage backups and disk space. A retention policy defines how many backups Oracle stores at at time. For example, if a retention policy requires that three full backups are available at all times, Oracle will automatically reclaim disk space used by older backups that are not required by the retention policy.
194 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
By using Oracle’s automatic disk-based backup and recovery policies, you do need need to manage disk space for your backups, simplifying backup management.
Disk quota for the recovery area You must allocate a disk quota for the recovery area. The size of the disk quota depends on factors such as your backup policies and the amount of changes occurring on the database. Note: By default, the packaged Oracle 10g server sets a disk quota for the recovery area to 10GB. You can configure the disk quota by setting the db_recovery_file_dest_size initialization parameter. To set the recovery area disk quota, connect to SQLPlus as a database administrator user and issue the following command SQL> alter system set db_recovery_file_dest_size = xxG scope=both; where xx is the size of the disk quota area you want to allocate. Oracle automatically manages the disk quota. If properly sized to accommodate your backup retention policies, you do not need to perform any administrative tasks. Oracle does not purge anything in the flash recovery area until the server needs to reclaim space. Over time, by default Oracle will consume the full 10GB allotment with backups prior to performing cleanup activities. At any time, you can manually purge the recovery by issuing the DELETE OBSOLETE command through RMAN.
Oracle’s Recovery Manager (RMAN) configuration and default policies The following table lists the default backup policies packaged with your Oracle 10g server for ESP Server. Policy Value Comment RECOVER WINDOW 2 Database can be recovered to any point or within the last 2 days or REDUNDANCY Database maintains 2 backups of each datafile and control file (default) BACKUP OPTIMIZATION ON CONTROLFILE AUTOBACKUP ON DEFAULT DEVICE TYPE TO DISK DB_RECOVERY_FILE_DEST_SIZE 10GB
ESPD-5.0-AG-01 195 Section–Troubleshooting
Troubleshooting
Oracle’s alert log tracks events reported by the database that require attention. You can find Oracle’s alert log in the following location:
UNIX $ORACLE_HOME/admin/ORACLE_SID/bdump
Windows %ORACLE_HOME%\admin\ORACLE_SID\bdump ORACLE_SID is the Oracle instance name. Look for messages starting with "ORA-". Each message contains a message number and a an error description.
Common administrative commands
The default administrative system ID and password for ESP Server’s embedded Oracle 10g database are • ID — sys • Password — cybermation
Starting an Oracle instance
To start an Oracle instance 1. Set your ORACLE_SID environment variable to the instance name of the database you want to start. UNIX ORACLE_SID=instance_name; export ORACLE_SID Windows set ORACLE_SID=instance_name 2. Connect to the database using SQLPlus. sqlplus /nolog 3. At the prompt, type the following commands: SQL> connect id/password@ORACLE_SID as sysdba; SQL> startup; SQL> quit;
196 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
Tip: On a Windows server, you can also start the Oracle instance through its Windows service.
Stopping an Oracle instance
To stop an Oracle instance 1. Set your ORACLE_SID environment variable to the instance name of the database you want to stop. UNIX ORACLE_SID=instance_name; export ORACLE_SID Windows set ORACLE_SID=instance_name 2. Connect to the database using SQLPlus. sqlplus /nolog 3. At the prompt, type the following commands: SQL> connect id/password@ORACLE_SID as sysdba; SQL> shutdown option; Replace option with one of the following: • blank or IMMEDIATE — Brings downs the database gracefully • ABORT — Shuts down the database disregarding its current transactional status. Note: Use ABORT only as a last resort if you cannot bring the database down gracefully. 4. Type the following command: SQL> quit; Tip: On a Windows server, you can also stop the Oracle instance through its Windows service.
ESPD-5.0-AG-01 197 Section–Common administrative commands
Starting and stopping the Oracle Listener The Oracle Listener process manages all connections to the Oracle instance. For clients to connect to the database, the Oracle Listener process must be running.
To start and stop the Oracle Listener 1. Log in as the Oracle user. 2. Change to the bin subdirectory. UNIX cd $ORACLE_HOME/bin Windows cd %ORACLE_HOME%\bin 3. Run the listener control utility with the appropriate option. %> lsnrctl option Replace option with one of the following: • start — Starts the Oracle Listener • stop — Stops the Oracle Listener • status — Returns the status of all the running listener processes • reload — Reloads the listeners configuration file. Use only if the listeners configuration file changed. Tip: On a Windows server, you can also start and stop the Oracle Listener process through its Windows service.
Checking the Oracle Listener’s status Oracle provides a test utility called tnsping. This utility is analogous to the usual network ping command, except that it tests the listener process. The syntax for this utility is the following: tnsping DATABASE_ALIAS DATABASE_ALIAS is the alias of the database you want to test, as defined in the tnsnames.ora file. In the following tsnames.ora file entry, the database alias appears in the first line of the definition (ESPRESSO): ESPRESSO = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = yourhostname)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = ESPRESSO) )
198 ESPD-5.0-AG-01 Appendix A–Oracle Administration Primer
) To test if the listener process is active and accepting connections to this database, issue the following command: %> tnsping ESPRESSO A successful test produces a result similar to this Attempting to contact (ADDRESS=(PROTOCOL=TCP)(HOST=yourhostname)(PORT=1521))
OK (10 msec) Note: Pay attention to the round trip (10 msec in the above example). A high round trip (for example, over 500 msec) can sometimes indicate network or database server resource usage issues.
Useful queries
Once connected to the Oracle instance, you can perform the following queries through Oracle’s SQLPlus tool. Oracle provides several dynamic views to help you troubleshoot.
Checking the Oracle server version select * from v$version;
Checking the status of the database instance (SID) select * from v$instance; This command returns the following information: • instance_number •thread# • instance_name • archiver • host_name • log_switch_wait •version •logins • startup_time • shutdown_pending • status • database_status • parallel • instance_role
Check free space by tablespace select tablespace_name,sum(blocks) from dba_free_space group by tablespace_name;
List all defined database users select username from all_users order by username;
ESPD-5.0-AG-01 199 Section–Useful queries
List all the database objects owned by a particular user select object_type, object_name from all_users where OWNER='username' order by object_type, object_name;
Describing the physical structure of a table or view describe object_name; Replace object_name with the table or view name.
List users and their database role privileges select * from dba_role_privs where grantee='username';
List of modifiable Oracle parameters select name,value from v$parameter;
List all defined tablespaces and associated physical datafile information select * from v$datafile a, v$tablespace b where a.TS#=b.TS#;
Describe the SQL that was used to create a database view select view_name, text from dba_views where view_name='viewname';
Determine the amount of memory allocated to the Oracle instance select * from v$sga;
200 ESPD-5.0-AG-01 Using the Import/Export Utility
You can use the import/export utility in batch or interactive mode to import and export artifact definitions such as Alerts, Applications, calendars, Events, forecasts, JavaScript scripts, and resources. For example, you may want to export your Application definitions to a directory, update the Applications outside of the ESP database, and import the changed definitions back into the ESP database. All artifact definitions, except javascript, config and sundry, are stored as XML files.
Syntax The import/export utility uses the following command syntax:
UNIX imexutil.sh [-h host] [-p port] [-u user] [-w password] [-c cmd] [-help]
Windows imexutil.bat [-h host] [-p port] [-u user] [-w password] [-c cmd] [-help]
Operand Description host ESP Server IP address or DNS name port ESP Server port user The client user ID
ESPD-5.0-UG-01 201 Section–Commands
Operand Description password The client user ID password cmd The command(s) or file containing commands to issue in batch mode. If not specified, interactive mode is invoked. You can specify a list of commands separated by semi-colons or a file containing the commands, indicated by prefixing the file name with an @ sign. For example:
-c "exportapplication -outdir c:\applications"
-c "exportapplication -outdir c:\applications; exportevent -outdir c:\events"
-c @C:\commands.txt Note: If the argument contains a space, enclose the argument within quotes, for example -c "@input file.txt". help Displays help. If specified, other options are ignored.
Commands
Importing definitions Use the import command to import artifact definitions from files and directories. Files are processed before directories. If an error is encountered processing an artifact, processing continues with the next artifact. The import command uses the following syntax: importartifact [-file filenames] [-dir dirnames]
Operand Description artifact The artifact name. Use any of the following artifact names: • agent — ESP Agent definitions from the ESP Server topology • alert — ESP Alert definitions • application — ESP Application definitions • calendar — ESP calendar definitions • config — ESP Server configuration parameters • event — ESP Event definitions • forecast — definitions used for forecast reports • javascript — JavaScript scripts stored in the JavaScript repository • resource — resource definitions • sundry — artifacts not covered in other artifact categories, such as global system-level symbolic variables filenames A list of file names separated by spaces. Name masking is not supported. Files are loaded before directories. dirnames A list of directory names separated by spaces. Name masking is not supported. Directories are loaded after files.
202 ESPD-5.0-UG-01 Appendix B–Using the Import/Export Utility
Exporting definitions Use the export command to export artifact definitions to a directory. If an error is encountered processing an artifact, processing continues with the next artifact. The export command uses the following syntax: exportartifact [-outdir outputdir]
Operand Description artifact The artifact name. • agent — ESP Agent definitions from the ESP Server topology • alert — ESP Alert definitions • application — ESP Application definitions • calendar — ESP calendar definitions • config — ESP Server configuration parameters • event — ESP Event definitions • forecast — forecast definitions used for forecast reports • group — group definitions used for security • javascript — JavaScript scripts stored in the JavaScript repository • resource — resource definitions • sundry — artifacts not covered in other artifact categories, such as global system-level symbolic variables • user — user definitions used for security outputdir The directory the artifact definitions are exported to. If not specified, the artifacts are exported to the current working directory.
Authenticating a user Use the user command to authenticate a user. The user command uses the following syntax: user userid password
Operand Description userid The user ID to be authenticated password The password for the user ID
Terminating a session Use the end command terminates a session. The end command uses the following syntax. end
Examples The following examples export all Applications to c:\applications and all calendars to c:\calendars.
ESPD-5.0-UG-01 203 Section–Examples
Batch commands imexutil.bat -h esp -p 7500 -u schedmaster -w schedmaster -c "exportapplication -outdir c:\applications; exportcalendar -outdir c:\calendars"
Batch command file imexutil.bat -h esp -p 7500 -c @c:\commandfile.txt The commandfile.txt file contains the following: user schedmaster schedmaster exportapplication -outdir c:\applications exportcalendar -outdir c:\calendars
Interactive imexutil.bat -h esp -p 7500 -->user schedmaster schedmaster Logged on successfully to application server. -->exportapplication -outdir c:\applications Attempting to export application VERIFY Exported application definition VERIFY version 1 -->exportcalendar -outdir c:\calendars Attempting to export calendar SYSTEM Exported calendar definition SYSTEM version 1 -->end Session terminated
204 ESPD-5.0-UG-01 Index
A APPL permission,76 about command, 170 Application generations, resetting,155 ADMIN default user,62 Applications that fail to generate, setting up ADMIN permission,72,76 notifications,24 Admin perspective APPLX permission,78 admin user,10 archive database logs, 132, 133, 134, 152, 153 views,10 artifact definitions ADMIN.Network Topology permission,72 exporting,203 ADMIN.Security Files permission,73 importing, 202 ADMINGRP group,63 artifacts in the system, viewing a list,26 afmlog filterid command,168 audit log afmlog purge command, 168 creating report,98 afmlog spin command,168 information,98 agent command, 168 auditlog export command, 169 AGENT permission,73 automatic failback, 106, 109 agentmsg control command,168 AGENTMSG permission,74 B AGENTUSER permission,75 blocks, database storage,192 ALERT permission,76 appcmd commands description,168 C ESP Agent,168 CALENDAR permission,79 ESP Server commands,170 changerole command,170 log commands,168 CMD permission,80
ESPD-5.0-AG-01 205 cold start ESP Agent definition,17 changing user’s password,57 performing,17 clearing log files,161 Command Utility,171 clearing spool files,162 batch,173 controlling,58 interactive,172 defining users,56 syntax,172 description,7 completed jobs, clearing,156 modifying configuration parameters,55 completedjobs purge command,171 reloading security file,59 configuration parameters stopping,58 ESP Agent,55 ESP Agent for z/OS, configuring,57 Espresso Server,22 ESP Agent receiver messages instance,22 holding and resuming,59 shared,22 ESP Agent receiver messages, clearing,59 connections ESP artifact types,26 standby database,141 ESP Desktop Client console.txt backup files, clearing, 158 administrator’s component,10 control files applying software updates,13 about,191 description,6 protection, 152 passwords,11 countlist command server connections,11 description,170 viewing users connected,12 using,26 ESP High Availability configuration models, 114 D detection,108 process, 107 Data Guard requirements,115 see Oracle Data Guard terminology,106 data manipulation language verifying the configuration,118 see DML ESP High Security database installation steps,30 changing,141 ESP Server ,106,110 failover archiving log files, 157 see also relational database changing port numbers,23 ,151 database backup, creating changing the Windows service name,30 ,191 datafiles checking status,16 disaster recovery solution,132 clearing completed jobs repository,156 see also Oracle Data Guard configuring,22 ,27 disk monitoring ESP Agent description,6 disk space availability, shared directory,27 filter IDs,101 display afmlog command, 169 instance and shared parameters,22 ,169 display auditlog command log files,96 display tracelog command,169 recycling,20 display workloadobject command,171 start type,17 ,132,133 DML starting,18 startup in failover configuration,107 E stopping,20 email addresses, changing,23 ESP Server log files
206 ESPD-5.0-AG-01 Index
see log files H ESP Server roles, switching,112 heap size, checking,25 ESP_DATA, 191, 193 ESP_HIST, 191, 193 ESP_HISTX,191,193 I ESP_INDEX, 191, 193 import/export utility, syntax,201 ESP_TEMP, 190 ESP_UNDO, 190 J EVENT permission,81 jobs forced to complete, setting up notifications,25 EVENTX permission,82 EVERYONE group,63 exception messages,96 L exporting audit log,98 license status,26 extents,192 licensestatus command, 170 listener F see Oracle Listener process log files,96 failback applying permanent filter IDs,100 automatic, 106, 109 applying temporary filter IDs,99 changing the type,112 archiving,157 manual,106,110 archiving automatically,157 failover archiving manually, 158 configuring detection,110 changing location/name,97 database,106,110 clearing,159 filter IDs manually,159 about,96 clearing automatically,159 applying permanent, 100 exception messages,96 applying temporary,99 filter IDs,96 summary,101 filtering messages,99 filtering messages,99 maintenance,96 flash recovery area,152,153 rotation,157 about,194 types,96 disk quota,195 retention policy, 194 full client (OCI),187 M manual failback, 106, 110 G maximum availability mode,133 maximum performance mode,133 group description, changing,70 maximum protection mode,133,134 group permissions, adding, changing or removing,69 memcheck command, 170 groups memcheck command, using,25 ADMINGRP,63 memory usage, checking,25 creating,69 Micro Focus description,62 security rule,41 EVERYONE,63 OPERGRP,64 predefined,63 N removing from the ESP Server topology,70 nohup files SCHEDGRP,64 clearing,165
ESPD-5.0-AG-01 207 description,165 segments,193 notifications server components,190 setting up for Applications that fail to starting instance,196 generate,24 stopping instance,197 setting up for jobs forced to complete,25 tablespaces,190 TNS network protocol,186,187 O troubleshooting,196 undo segments,192 OPERGRP group,64 Oracle Listener Process Oracle Data Guard about,186 , 132, 133, 134, 152, 153 archive logs starting, 149, 198 , 141 connecting to standby database command line,149 DML,133 Windows service,149 , 134 implementation requirements status,198 ,133 maximum availability mode stopping, 198 maximum performance mode,133 command line,151 ,133,134 maximum protection mode Windows service,152 overview, 132 Oracle Listener process primary database,132,133 starting,149 protection modes,133 stopping, 151 redo logs, 132, 133, 134 Oracle packaged database standby database,132,133 creating a standby, 136 zero data loss,133 setting environment variables,148 Oracle database starting,148 about,184 stopping, 149 administrative commands,196 Oracle Recovery Manager (RMAN),195 ,196 alert log ORACLE_HOME, 186, 187 backup and restore,194 ORACLE_SID,148 blocks,192 client communication,187 components,184 P configuration files, 187 packaged relational database control files,191 see relational database database storage,192 passwords datafiles,191 changing,11 default parameters,189 resetting,12 default system ID,196 permissions directory structure,185 adding, changing or removing,67 extents, 192 ADMIN,72,76 initialization files, 189 ADMIN.Network Topology,72 instances ADMIN.Security Files,73 (SID), 186, 187, 188, 189, 190, 194, 196 AGENT,73 Listener process,186 AGENTMSG,74 network components, 186 AGENTUSER,75 objects, 193 ALERT,76 queries,199 APPLX,78 redo logs, 192, 194 CALENDAR,79 retention policy, 194 CMD,80 schemas,193 conventions,65
208 ESPD-5.0-AG-01 Index
description,64 security rules summary,72 Micro Focus,41 user vs group,65 segments,193 primary database,132,133 server.log files product updates, receiving notifications,2 clearing,161 description,161 R setjdbcurl command,170 shared directory , 132, 133, 134, 153, 192, 194 redo logs monitoring,27 relational database monitoring availability,29 ,152,153 archive logs shared-file system,116 ,141 changing SID, 186, 187, 188, 189 changing connectivity properties,131 SMTP server name, changing,23 changing the name,142 SNMP Manager ,154 clearing changing settings,124 control files,152 third-party configuration,125 ,148 default system ID SNMP Manager, using third-party, 122 description,130 SNMP Message Viewer ESP High Availability, 130 removing messages,127 flash recovery area,152,153 SNMP messages ,153 full recovery description,122 history reporting,130 opening,127 partial recovery, 153 printing, 127 ,152 recovering receiving,126 redo logs,153 removing,127 resource management, 130 saving,127 ,149 starting database instance understanding,122 manually,150 viewing in text format,127 Windows service,150 SNMP trap receiver ,171 resetgen application command stopping, 126 RESOURCE permission,83 software updates for ESP Desktop Client,13 retention policy, 194 SQL,132 standby database, 132, 133 S connecting Espresso to,141 SCHEDGRP group,64 start type, ESP Server,17 SCHEDMASTER default user,62 starting schemas,193 database instance, 149 security manually,150 creating groups,69 Windows service,150 creating users,66 Oracle instance,196 deleting users,68 Oracle Listener process, 149, 198 description,62 command line,149 groups,62 Windows service,149 permissions,64 stop command, 170 permissions summary,72 stopping setting up,84 Oracle instance,197 users,62 Oracle Listener process,198 security file, reloading,59 command line,151
ESPD-5.0-AG-01 209 Windows service,152 creating,66 SYSTEM, 190 deleting,68 description,62 T removing from a group,68 removing from the ESP Server topology,68 ,190 tablespaces SCHEDMASTER default user,62 thin client (jdbc),187 TNS network protocol, 186, 187 full client (OCI),187 V thin client (jdbc),187 virtual Agent tracelog filterid command,169 removing parent,55 tracelog purge command,169 tracelog spin command,169 W warm start, definition,17 U Windows service name for ESP Server, changing,30 undo segments,192 users Z adding to a group,67 ADMIN default user,62 zero data loss, 133, 134 changing names,68
210 ESPD-5.0-AG-01