Enterprise PeopleTools 8.50 PeopleBook: Change Assistant

Configuring and Running Environment Management Components

This chapter discusses how to:

Configure the Environment Management hub.
Run the Environment Management hub.
Configure an Environment Management agent.
Run an Environment Management agent.
Run the viewer.
Handle common error conditions.
Configure and start an Environment Agent on z/OS.

Configuring the Environment Management Hub

Before you can run the Environment Management hub, you must ensure that it's properly configured.

The hub issues automatic recrawl and revalidate commands to the agents, and it can be configured to accept automatic updates from Change Assistant. You configure the hub by setting appropriate parameters in its configuration file, which is located as follows:

WebLogic:

PIA_HOME\webserv\domain\applications\peoplesoft\PSEMHUB\envmetadata\config\configuration.properties
WebSphere:

PIA_HOME\webserv\server\installedApps\domainNodeCell/domain.ear\PSEMHUB.war/envmetadata/config\configuration.properties

The following table describes the primary configuration.properties parameters for the hub:

Configuration Parameter	Description	Default Value
recrawlinterval	The interval, in hours, between two successive recrawl commands that have been issued to a peer. The server issues recrawl commands only to agents that are connected to the hub and have no pending messages in the queue. This configuration parameter is ignored by the agent.	24 hours Note. A 0 value means that it will not recrawl. Recrawling includes a revalidating.
revalidateinterval	The maximum time, in hours, between two successive automatic revalidates that the hub issues.	6 hours Note. A 0 value means that it will not revalidate.

Configuration Parameter

Description

Default Value

recrawlinterval

The interval, in hours, between two successive recrawl commands that have been issued to a peer. The server issues recrawl commands only to agents that are connected to the hub and have no pending messages in the queue. This configuration parameter is ignored by the agent.

24 hours

Note. A 0 value means that it will not recrawl.

Recrawling includes a revalidating.

revalidateinterval

The maximum time, in hours, between two successive automatic revalidates that the hub issues.

6 hours

Note. A 0 value means that it will not revalidate.

Hub Security Considerations

Environment Management framework does not support HTTPS connections. The agent and hub communicate using standard HTTP only.

On WebSphere, or for a single server configuration on WebLogic, PSEMHUB is a web application running within PIA. If PIA is configured to be accessed using HTTPS, you need to configure a separate server instance for the hub to enable the HTTP connections between agents and hub.

Configuring Hub Logging

The Environment Management hub logs are located as follows:

WebLogic: PIA_HOME\webserv\domain\applications\peoplesoft\PSEMHUB\envmetadata\logs
WebSphere: PIA_HOME\webserv\ps1\installedApps\<domain>NodeCell/<domain>.ear\PSEMHUB.war/envmetadata/logs

Edit the .....\PSEMHUB\envmetadata\config\Logconfig.properties to configure logging for the hub. The following two Logconfig.properties parameters, which determine the maximum size of each log file, and the amount of log files rolled over, can be changed:

log4j.appender.R.MaxFileSize=1024KB
log4j.appender.R.MaxBackupIndex=1"

Running the Environment Management Hub

This section discusses how to:

Run the hub on a single server.
Run the hub on multiple servers.

Before you run the Environment Management agent, you must first ensure that it's properly configured in the hub's configuration.properties file.

Running the Hub on a Single Server

On a single server, the PSEMHUB starts within PIA, so use the command you use for your web server to start PIA.

Running the Hub on Multiple Servers

Environment Management also supports multi-server installs. However, the Environment Management hub does not support clustering. The Environment Management hub persists metadata into the file system on the J2EE container. This is not replicated in a clustered environment. You experience erroneous behavior when you attempt to run the Environment Management hub in a clustered environment.

The Environment Management hub deals with large binary files that Change Assistant sends to the agents by using the hub as the intermediary dispatcher. This can create significant overhead to a production system that is running on a multi-server clustered environment. Therefore, PSEMHUB must always run on separate servers dedicated to the Environment Management hub requests.

Starting PSEMHUB on Multiple Servers on WebLogic

In a multiple server configuration, the PSEMHUB server listens on port 8081, by default.

Use the following steps to start the WebLogic hub:

Configure the Environment Management hub to run on a server that is different from the PeopleSoft Internet Architecture servers.
Configure the reverse proxy to redirect any network traffic with a uniform resource identifier (URI) of PSEMHUB to the server running the Environment Management hub.

On the machine from which the RPS application runs, access the HttpProxyServlet folder.

Select PSEMHUBHttpProxyServlet and click the Init Params tab. Replace WebLogicHost , WebLogicPort with the host and port from which your PSEMHUB server listens.

Note. Save your new configuration.

Use the following commands in sequence to start the Environment Management hub in a multi-server installation:...\StartWebLogicAdmin.cmd (start the admin server) ...\StartManagedWebLogic.cmd RPS ...\StartManagedWebLogic.cmd PSEMHUB

Then use the following URL to access PSEMHUB: http://RPS host:RPS port/PSEMHUB/hub.

Note. For a single server install using a reverse proxy, this additional step needs to be performed in order for the Environment Management hub to be able to process the PSEMHUB requests. You need to edit: PIA_HOME\webserv\domain\applications\HttpProxyServlet\WEB-INF\web.xml. In the PSEMHUBHttpProxyServlet section, change the default port from 8001 to 80.

The following is a sample configuration: - <servlet> <servlet-name>PSEMHUBHttpProxyServlet</servlet-name> <servlet-class>weblogic.servlet.proxy.HttpProxyServlet</servlet-class> - <init-param> <param-name>WebLogicHost</param-name> <param-value>localhost</param-value> </init-param> - <init-param> <param-name>WebLogicPort</param-name> <param-value>80</param-value> </init-param> </servlet>

Start the WebSphere Hub on Multiple Servers

If you are using multiple servers, then you need to dedicate one of them to handle PSEMHUB requests. All PSEMHUB requests should be routed to the same server instance. The following steps show the configuration changes that are required for this purpose:

Edit your reverse proxy's plug-in configuration file (plugin-cfg.xml) then make sure that only one server is dedicated to PSEMHUB.
Remove this line from all other servers: <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/PSEMHUB/*" />. The server you chose for PSEMHUB should only service PSEMHUB requests so that it can run independently and can be shut down without affecting the rest of the system.
Restart the reverse proxy using : IBM_proxy_base_directory\bin\apachectl restart.
Restart all the servers. For Windows, the directory is: WebSphere_Appserver_directory\bin\startServer.bat serverX. For UNIX, the directory is: WebSphere_Appserver_directory/bin/startServer.sh serverX.
Use the following URL to access PSEMHUB http://reverse_proxy_host:reverse_proxy_port/PSEMHUB/hub.

The reverse proxy's listen port is defined in IBM_reverse_proxy_base_directory\conf\httpd.conf.

Stopping the PSEMHUB on Multiple Servers on WebLogic

In a multiple server environment, target the server which is dedicated to PSEMHUB then execute PIA_HOME\webserv\domain\stopWebLogic.cmd PSEMHUB on Windows and PS_HOME/webserv/domain/stopWebLogic.sh PSEMHUB on UNIX. This will only stop the server servicing PSEMHUB requests. The other servers will still be up processing PIA requests.

The following is a sample XML configuration file for the WebLogic multi-server installation:

    1.1 Sample XML configuration file for WebLogic Multiserver installation
<UriGroup Name="default_host_server1_st-lnx06_Cluster_URIs">
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/*" /> 
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/PSIGW⇒
/*" /> 
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="⇒
/PSINTERLINKS/*" /> 
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/PSOL⇒
/*" /> 
</UriGroup>
- <UriGroup Name="default_host_server1_pt-lnx03_Cluster_URIs">
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/*" /> 
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/PSIGW⇒
/*" /> 
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="⇒
/PSINTERLINKS/*" /> 
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/PSOL⇒
/*" /> 
</UriGroup>
- <UriGroup Name="default_host_server1_pt-ibm15_Cluster_URIs">
  <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="⇒
/PSEMHUB/*" /> 
</UriGroup>

Stopping PSEMHUB on Multiple Servers on WebSphere

In a multiple server environment, target the server which is dedicated to PSEMHUB then execute WebSphere_Appserver_directory\bin\stopServer.bat serverX on Windows and WebSphere_Appserver_directory/bin/stopServer.sh serverX on UNIX. This will only stop the server servicing PSEMHUB requests. The other servers will still be up processing PIA requests

Configuring an Environment Management Agent

Before you can run an environment management agent, you must ensure that it's properly configured. You configure the agent by making appropriate entries in its configuration.properties file, which is located under:

PS_HOME\PSEMAgent\envmetadata\config

The following table describes the configuration.properties parameters for the Environment Management agent:

Configuration Parameter	Description	Default Value
hubURL	The URL that contains the host name and the port number of the machine on which the Environment Management hub is running (inside a J2EE container).	http://hostname:port/PSEMHUB/hub.
agentport	A port that the agent uses for internal life cycle management.	5283.
pinginterval	The interval, in milliseconds, between two successive attempts that the peer makes to contact the hub. All peers that access this configuration file have the same ping interval.	10000 (in milliseconds for the heartbeat) Note. The minimum required pinginterval value is 1000.
windowsdrivestocrawl	On Microsoft Windows, the set of local drives or directory paths where PS_HOME, PS_CFG_HOME and PIA_HOME are located. Separate the drive letters or directory paths with spaces and a pipe symbol ( \| ).	c: \| d: Note. Do not leave a trailing '/' or '\' character at the end of the path.
unixdrivestocrawl	On UNIX, the set of local drives or directory paths where PS_HOME, PS_CFG_HOME, and PIA_HOME are located.	$HOME Note. Do not leave a trailing '/' or '\' character at the end of the path.
chunksize	Only applicable to large files, which may be chunked when sent. The chunksize represents the maximum size in bytes of each chunk.	1048576 (1 MB) (used for large file transfers).

Configuring Agent Logging

The Environment Management agent's logs are located under PS_HOME\PSEMAgent\envmetadata\logs.

Edit PS_HOME\PSEMAgent\envmetadata\config\Logconfig.properties to configure the logging for the agent.

The following parameters determine the maximum size of each log file and the amount of log files rolled over. You can change the values of these parameters.

log4j.appender.R.MaxFileSize=1024KB
log4j.appender.R.MaxBackupIndex=1"

Configuring Agents With a Secure PS_HOME

Change Assistant deploys the updates to the PS_HOME using the agents running on the managed servers. Therefore, the agent running on a server should have write access to the PS_HOME and its subdirectories.

Note. While specifying the crawl path in configuration.properties, make sure that the decoupled configuration home (PS_CFG_HOME) is also included.

Running an Environment Management Agent

This section discusses how to:

Run an agent.
Start an agent automatically in Windows.

Running an Agent

Before you run an Environment Management agent, you must ensure that it's properly configured in the agent's configuration.properties file.

Starting the Agent

At a command prompt, navigate to PS_HOME\PSEMAgent.

Use one of these scripts to start the Environment Management agent:

On Microsoft Windows, run PS_HOME\PSEMAgent\StartAgent.bat.

Note. If you want the agent to start automatically when the machine starts, use the Microsoft Windows service that's delivered as part of PeopleTools. Or, you can add the script to the startup applications.
On UNIX, run PS_HOME/PSEMAgent/StartAgent.sh.

Note. If you want the Environment Management agent to start automatically on UNIX when the machine starts, add StartAgent.sh to the login/boot scripts.

The first time an agent starts, it crawls the machine to locate PeopleSoft elements on that machine. The results of searching the hard disk are saved in the envmetadata\data\search-results.xml file.

Note. When starting an agent manually from the command prompt or from a script, the command prompt will continue to stay open, and it is normal to see the output of the periodic heartbeat events ("sending pulse") in the command prompt as the agent communicates with the hub. By default these "pulses" are every 10 seconds, except when environment information is being uploaded to the hub. You can configure the agent to run in the background using the provided Windows service, and on UNIX by using the nohup command. These options are documented in other sections of this PeopleBook.

Note. Only one Environment Management agent can be started per machine. If an agent is already started, you may receive error messages indicating that the agent cannot be started because there is already one running on the machine.

See Starting an Agent in the Background on UNIX.

See Starting an Agent With PSEMAgent Windows Service.

Starting the Agent on a Secure PS_HOME

On Microsoft Windows:

Create a new shortcut from the desktop (right-click, New, Shortcut).
In the Type the location of the item enter:

runas /user:<domainname>\<username> <PS_HOME>\PSEMAgent\StartAgent.bat

For example:

runas /user:bigcompany\Tsawyer c:\ptinstalls\pt850\PSEMAgent\StartAgent.bat

Where the user specified has write access to PS_HOME.
Click Next, and enter a name for the shortcut.
Use this shortcut to start the agent.

On UNIX:

Log in as the user who has write access to the PS_HOME.
PS_HOME/PSEMAgent/StartAgent.sh.

See Securing PS_HOME and PS_CFG_HOME.

Stopping the Agent

Use one of these scripts to stop the Environment Management agent:

On Microsoft Windows, run PS_HOME\PSEMAgent\StopAgent.bat.
On UNIX, run PS_HOME/PSEMAgent/StopAgent.sh.

Recrawl

If you install new software components, the running Environment Management agent doesn't automatically detect them. This is because, to improve performance, the agent doesn't crawl every time it starts up. Instead it crawls only if the search-results.xml file does not exist.

You can force a recrawl and make the new components manageable by reissuing the StartAgent command with the recrawl option:

Open a new command line window.
Change directories to PS_HOME\PSEMAgent.
Issue the following command:
```
StartAgent recrawl
```
This forces a recrawl and creates a new search-results.xml file. If an agent is already running, it publishes the results to the hub.

If the running Environment Management agent is connected to the hub constantly, the recrawl interval occurs every 24 hours by default. If the agent has not been connected to the hub for a few days, the hub requests the agent to recrawl when the agent contacts the hub the next time.

Note. Recrawling includes revalidating.

Revalidate

If the Environment Management agent does not recognize any of the installed components, the search-results.xml file may not exist or may contain only an entry for Host. The problem may be that the agent needs to have permission to read directories as well as execute programs. Grant these permission for the agent. Also check whether the agent has permission to create a file on the local file system. Finally, check whether the disk is full. The agent might have no disk space to create a search-results.xml file.

If the hub is not running, you may receive the following error messages in the agent log or console:

Broken connection - attempting to reconnect
RemoteException while connecting to server - retrying attempt 1
RemoteException while connecting to server - retrying attempt 2
RemoteException while connecting to server - retrying attempt 3

Once the Environment Management hub is back up, the agent will successfully connect. There's no need to stop and restart the agent.

Note. If you are performing a recrawl, you don't need to separately revalidate.

Command-Line Arguments for the Agent

You can run these command-line arguments with the startAgent.bat (or startAgent.sh) script.

Argument	Description	Sample Output
version	Returns the version of the agent.	Version:8.45 Build Number: 109
shutdown	Shuts down a previous instance of the agent if it is running.	If the agent does not exist: Shutting down Agent.... Unable to detect a running agent... Instance does not exist If the agent exists: Shutting down Agent.... Shut down normally
url	Prints the URL of the hub with which the agent is configured to communicate.	http:// 216.131.222.227:80/PSEMHUB/hub
validate	Validates the current set of managed components that have been discovered from the last crawling by the agent.	Not applicable (NA)
recrawl	Recrawls the hard disk to detect new configurations. Recrawls the detected database environments to update database information. The current search-results.xml file is backed up. Note. Recrawling includes revalidating.	NA
isrunning	Returns true if an agent is already running and false if an agent is not already running.	NA
remove	Removes the peer and all its registered components from the hub.	Removal Completed- PeerID 2 has been removed. Removal Failed- PeerID 2 could not be removed from the hub.

Starting an Agent in the Background on UNIX

Use the UNIX nohup command with the StartAgent.sh script to start an agent automatically and run in the background. This enables you to avoid having a command prompt open at all times showing the constant heartbeat of the agent. You can specify an output file to store heartbeat information.

For example,

nohup ./StartAgent.sh > agent_output.log &

Starting an Agent With PSEMAgent Windows Service

You can set an Environment Management agent to start automatically when your Environment Management machine boots and run in the background. This enables you to avoid having a command prompt open at all times showing the constant heartbeat of the agent.

For this option, use the PSEMAgent Windows service that's delivered as part of PeopleTools.

Installing the PSEMAgent Service

You install the PSEMAgent service from a command prompt. Copies of the install program are located in two places:

PS_HOME\bin\client\winx86

PS_HOME\bin\server\winx86

To install the PSEMAgent service:

At a command prompt, change to either location of the install program.
Enter the following command:

PSEMAgentService /install PS_HOME\PSEMAgent

Where PS_HOME is the PeopleTools installed location.

The PSEMAgent service is now installed, but not started. It's configured by default to start automatically when the system boots, and to log on using the local system account. You can start it manually, or wait for the next reboot.

Note. The PSEMAgent service is configured to start as an automatic service, by default. However, the Hub must be running prior to the PSEMAgent service attempting to start, or the PSEMAgent service will not start successfully. It is recommended to set the PSEMAgent service to manual start in the Windows Services interface. Then, to start the PSEMAgent service, start it manually from the Services interface.

Starting the PSEMAgent Service

You can start the PSEMAgent service from a command prompt, or from the Windows Services control panel. The name of the service follows this convention: PeopleSoft Environment Management Agent-<release>.

To start the PSEMAgent service from a command prompt, use the NET START command. For example:
```
NET START "PeopleSoft Environment Management Agent-8.50"
```
To start the PSEMAgent service from the Windows Services control panel:
1. Open the Windows Control Panel, then double-click Administrative Tools, then Services.
2. In the Services control panel, right-click the PeopleSoft Environment Management Agent entry and select Start.

Stopping the PSEMAgent Service

You can stop the PSEMAgent service from a command prompt, or from the Windows Services control panel.

To stop the PSEMAgent service from a command prompt, use the NET STOP command. For example:
```
NET STOP "PeopleSoft Environment Management Agent-8.50"
```
To stop the PSEMAgent service from the Windows Services control panel:
1. Open the Windows control panel, then double-click Administrative Tools, then Services.
2. In the Services control panel, right-click the PeopleSoft Environment Management Agent entry and select Stop.

Uninstalling the PSEMAgent Service

You uninstall the PSEMAgent service from a command prompt.

To uninstall the PSEMAgent service:

At a command prompt, change to either location of the uninstall program.

Copies of the uninstall program are located in two places:

PS_HOME\bin\client\winx86

PS_HOME\bin\server\winx86
Enter the following command:

PSEMAgentService /uninstall

PSEMAgentService determines if the service is currently started, and automatically stops it before completing the uninstall operation. You'll see messages reporting on the status of the operation.

Note. If the service is currently stopped, you'll see an error message indicating that it can't be stopped. Regardless of this, the uninstall operation completes normally.

Monitoring Agent Status

If the Hub does not receive status from a peer for three ping cycles ("I am alive" messages) then it changes the state of the peer from Running to Not Running. Information related to agent status can be accessed from a browser using the following URL:

http://hub_host:hub_port/PSEMHUB/hub

Running the Viewer

To view data from the Environment Management hub:

Run a Java program to connect to the hub and retrieve the information in XML format.

Run the appropriate script for your environment in from PS_HOME\PSEMViewer. You will be prompted for the web server's listening port.
- UNIX: ./GetEnvInfo.sh
- Windows: GetEnvInfo.bat
  
  Note. For security reasons, the Java program connects only to the local host.
Open PS_HOME\PSEMViewer\envmetadata\data\viewer.html to view the information in the generated XML file.

Integrating with Oracle Configuration Manager

Oracle Configuration Manager (OCM) is used to collect configuration data from customer environments and upload that data to a Customer Configuration Repository (CCR) stored and managed by Oracle. OCM works in tandem with PeopleSoft EMF for collecting configuration data from a PeopleSoft environment. The OCM data collection agents collect configuration data using the feed provided by the PeopleSoft EMF agents.

The PSEMAgent has to be running on the instance so that configuration data can be collected. After crawling the environment, PSEMAgent writes the environment data in XML format (with a .psft extension) to the PS_HOME/ccr/state directory.

OCM is installed and configured on a PeopleTools environment as part of the application server, Process Scheduler server, and web server PeopleTools installation. You can also install and configure OCM by directly downloading the standalone install kit from My Oracle Support.

Configuring and Starting an Environment Management Agent on z/OS

To run an agent on z/OS, you must have installed JRE delivered with PeopleTools on the z/OS machine.

To configure and start the agent on z/OS:

Edit the configuration.properties file (PS_HOME/PSEMAgent/envmetadata/config).
Edit hubURL and define the hub machine name and hub port.
Edit unixdrivestocrawl and set it to the set of directories that need to be crawled.
Edit StartAgent.sh.

On the first line, replace PS_HOME with your PS_HOME location.

Edit the last line to point to your JRE location.
Edit StopAgent.sh.

On the first line, replace PS_HOME with your PS_HOME location.

Edit the last line to point to your JRE location.

The default charset on z/OS is EBCDIC. If you wish to view the content of PS_HOME/PSEMAgent/envmetadata/data/search-results.xml, you need to run the following commands:

cd PS_HOME/PSEMAgent/envmetatda/data . PS_HOME/psconfig.sh PS_HOME/bin/psuniconv utf-8 search-results.xml ccsid1047 result.txt

This comment is also true for PS_HOME/PSEMAgent/envmetadata/data/matchers.xml.

You can find a viewable version of the results in result.txt. You can also FTP (binary) these files to a different machine running a different operating system and view them in any editor.