image
CHAPTER
6
Environment Management Framework
image he Environment Management Framework (EMF) is an essential component of upgrade management. It consists of an EMF hub and EMF agents. Agents running in each tier of a PeopleSoft installation gather information about the tier and relay that information to the hub. The hub receives and stores agent information for Change Assistant, which uploads this information to the Update Gateway to determine available updates. When applying updates, Change Assistant sends commands to the EMF hub, which dispatches these instructions to EMF agents. In this chapter, you will learn how to configure the EMF hub and EMF agents, a prerequisite for next chapter’s discussion of Change Assistant.
image NOTE
In other documentation you may see the EMF hub and EMF agent referred to as PSEMHub and PSEMAgent. PeopleSoft’s documentation uses both the EMF and PSEM prefixes when referring to the hub and agents.
The EMF Hub
The EMF hub is a PeopleSoft Internet Architecture (PIA) servlet installed in your PeopleSoft web servlets directory. On WebLogic, this is located at $PS_CFG_HOME/webserv/peoplesoft/applications/peoplesoft/PSEMHUB.war. On WebSphere, look in $PS_CFG_HOME/webserv/<cell_ node_server>/<domain>.ear/PSEMHUB.war/.
You can view the status of registered agents from your browser by accessing the URL http://hub_host:port/PSEMHUB/hub. On my Oracle VM instance, the EMF hub is currently running at the URL http://fscm912pt:8000/PSEMHUB/hub. (Later, we will move it to a standalone web server.)
Configuration
The EMF Hub configuration.properties file is in the envmetadata/config subdirectory of the PSEMHUB servlet. The hub is preconfigured at install to inspect (crawl) agents every 24 hours and revalidate agents every 6 hours. An administrator can change the crawl interval by setting a new value for recrawlinterval. Likewise, to revalidate on a different interval, change the revalidateinterval property. If these values are acceptable to your organization, you do not need to make any configuration changes to the EMF hub.
Logging
The EMF hub uses log4j, a Java logging framework that supports a variety of targets (called appenders) and formats. You can find full documentation for log4j on the Apache log4j web site at http://logging.apache.org/log4j/. The EMF hub log4j configuration is in the envmetadata/config/Logconfig.properties file. From this file, you can change the log file name and location, logging format, rotation schedule, and other information.
The default EMF hub log configuration uses the log4j RollingFileAppender. The RollingFileAppender rotates the log file when it reaches a certain size. The EMF hub log is configured to role when it reaches a maximum size of 1024 KB. An administrator can change the log size by setting a new value for log4j.appender.R.MaxFileSize. The maximum number of rotated logs is specified by the log4j.appender.R.MaxBackupIndex property. Alternatively, you could switch to the related DailyRollingFileAppender by changing the log4j.appender.R property as follows:
image
Clearing the EMF Hub Cache
If you clone, move, or change the architecture of a hub or its agents, you may want to clear the hub’s cache. When crawled, agents will repopulate the cache with current, relevant information. To clear the hub cache, follow these steps:
 
1.    Stop the PSEMHUB servlet container (web server).
2.    In the PSEMHUB/envmetadata web application directory, delete the following files and folders:
 
■   PersistentStorage
■   scratchpad
■   data/environment
■   data/proxies
■   data/state.dat
 
The following is a transcript from the latest purge of my EMF hub cache:
image
Configuring a Standalone EMF Hub
Even though the EMF hub is preconfigured to run in PIA, there are a few reasons to run it outside of PIA:
 
■   The EMF hub does not support clustering. If you have a clustered web server, you will need to run the EMF hub somewhere else.
■   The EMF hub and agents may share large amounts of information, placing a significant load on production servers.
■   For security, running the EMF hub on a standalone, lightweight servlet container offers an administrator a significant amount of flexibility.
 
To run the EMF hub in a standalone servlet container, first download and install a servlet container. A few of the more popular servlet containers include Apache Tomcat, Jetty, Glassfish, WebLogic, and JBoss (the latter three being full-blown Java 2 Enterprise Edition [J2EE] servers). After installing a servlet container, copy all of the files from a PIA server’s PSEMHUB.war file into the servlet container’s web application directory. Even though the PSEMHUB web application uses log4j, it doesn’t actually include the log4j jar file in its lib directory. Before starting up the PSEMHUB, download the Apache log4j 1.2.17 jar file into the PSEMHUB/WEB-INF/lib directory. You can obtain a copy of log4j from the Apache log4j download site at http://logging.apache.org/log4j/1.2/download.html. Be sure to verify the checksum and expand the archive.
The following listing is a transcript of the steps I used to migrate my PSEMHUB web application from a PIA instance to a standalone Tomcat instance:
image
image
image NOTE
For security reasons, the EMF Viewer application connects only to the localhost. If you move the EMF hub to a server without a PeopleTools install, then either reverse-proxy the EMF hub URL into a PeopleTools install localhost domain or copy the appropriate EMF Viewer files to the standalone EMF hub server.
EMF Agents
An EMF agent is a background process that runs on each server tier of a PeopleSoft application. On startup, these agents register themselves with the EMF hub and wait for the hub to issue commands. Unlike the EMF hub, EMF agents are not preconfigured and do not automatically start. To give the EMF hub a complete picture of a PeopleSoft installation, an administrator should configure and launch one EMF agent for each server host that has a PeopleTools installation. This includes file servers, application servers, process scheduler servers, and web servers.
Configuration
To configure an EMF agent, edit the configuration.properties file located in the $PS_HOME/PSEMAgent/envmetadata/config directory. Update the hubURL property to the URL of the instance’s web server URL. A few lines down, update the windowsdrivestocrawl for Microsoft Windows operating systems or unixdrivestocrawl for all other operating systems. The following is a partial listing of my EMF agent:
image
image NOTE
Drives are pipe (|) delimited and should all be listed on a single line. Regardless of operating system, use the slash (/) file path delimiter.
My installation is a standard Oracle VM two-host demo system installation consisting of a database host and a middle (PeopleTools) tier. My hubURL points to the localhost/loopback address because my web server, application server, and process scheduler server all exist on the same middle-tier host.
The term drive in the context of EMF is not a physical disk drive, but rather a file system starting point. As you can see from my unixdrivestocrawl example, I listed two directories: my PS_HOME directory and my PS_CFG_HOME directory. The agent will crawl these directories in search of PeopleSoft-specific metadata, identifying web servers, process scheduler servers, application servers, file servers, and even the PS_APP_HOME.
Decoupled Home Configuration
PeopleTools 8.50 introduced the PS_CFG_HOME decoupled configuration directory. PeopleTools 8.52 included a new PS_APP_HOME decoupled application installation directory. These new directory structures allow an administrator to decouple PeopleSoft’s installation files. Prior releases commingle PeopleTools, application, and configuration files within the same directory structure. The primary benefits of a decoupled home include these:
 
■   Security   A decoupled implementation allows a lesser privileged user to run the applications while still writing to configuration and log files. Proper HOME ownership allows for the security principle of least privilege.
■   Sharing   An implementation team can share a PS_HOME and/or a PS_APP_HOME across multiple PeopleSoft applications or instances, relying on the underlying hardware to provide redundancy and failover.
■   Upgrade   Decoupling PS_HOME, PS_APP_HOME, and PS_CFG_HOME allows an administrator to replace a PS_HOME or PS_APP_HOME file system mount point with a new file system, thereby performing an instant middle-tier upgrade. You can read more about this upgrade option in Part III of this book.
 
If the PS_HOME and PS_APP_HOME are owned by separate users, you may have trouble performing upgrades with Change Assistant through the EMF hub and agents. Since an EMF agent creates and changes files in the $PS_HOME/PSEMAgent directory, the user running the EMF agent must have write access to the PSEMAgent directory. Likewise, the EMF agent user must have write access to the PS_APP_HOME directory to deploy files successfully. Changing user and group permissions on PS_HOME or PS_APP_HOME contents violates either the least privilege or compartmentalization principles and quite possibly both principles.
There are several solutions to this problem. One that maintains compartmentalization and least privilege is simply to copy the $PS_HOME/PSEMAgent directory into $PS_APP_HOME/PSEMAgent and then run the agent as the PS_APP_HOME owner. To perform an application upgrade for a host using Change Assistant, a site needs to run only one agent per PS_APP_HOME owner.
image NOTE
When running multiple EMF agents on the same host, be sure to configure each agent to use a different agentport.
Logging
The EMF agent log settings are very similar to the EMF hub settings, allowing for the same log4j flexible configuration. Unless your organization requires an alternate log file management strategy or prefers to centralize log management, an administrator should not have to make changes to the log file settings. On the other hand, if the EMF agent isn’t sending system details to the EMF hub, then changing the log level will provide the administrator with a significant amount of detail. To change the log level, edit $PS_ HOME/PSEMAgent/envmetadata/config/Logconfig.properties. Search for the line log4j.rootLogger=info, stdout, R. Then replace info with all and restart the agent:
image
The log4j logging framework supports the log levels all, trace, debug, info, warn, error, fatal, and off. All is on the verbose extreme, whereas off will stop logging altogether. The other levels are additive. The info level will log info, warn, error, and fatal messages whereas the error level will log only error and fatal messages. When I increased my log level to all, I saw everything from tnsping output to org.apache.commons.httpclient requests. An administrator can fine-tune logging levels and statements by logger name. Use the following configuration to log all EMF statements and only errors and warnings from other Java classes within the EMF agent:
image
Running the Agent
To launch an agent, run the operating system–specific batch file within the PS_HOMEPSEMAgent directory. For Microsoft Windows–based agents, run the following:
image
All other operating systems use the following:
image
As mentioned, the operating system user running the agent must have read/write access to the PSEMAgent directory as well as the $PS_APP_ HOME (or $PS_HOME) directory. The operating system user also requires a properly configured environment. As the agent crawls directories and discovers PeopleSoft metadata, it will run utilities to acquire additional information. When run on my Oracle Enterprise Linux middle tier, the EMF Agent executes psae and tnsping.
EMF Agents as Services
PeopleTools delivers an EMF agent service for Microsoft Windows. To install the service, open a command prompt and issue the following commands:
image
The service defaults to automatic startup, which means it will auto start when booting Microsoft Windows. Unfortunately, if the EMF hub is down, the service will fail to start. Oracle recommends changing the service startup type to Manual and then starting the service only after the EMF hub is running. Alternatively, use the StartAgent.bat script to start the EMF agent only when needed.
For all other operating systems, create the appropriate init script. Unlike the Microsoft Windows service, a properly written UNIX service will continue to ping the EMF hub even if the hub is down, logging errors and retry attempts until the hub is running.
Here is a copy of the Linux Standard Base (LSB)–compliant init script I wrote for my Oracle Enterprise Linux 5.8 middle tier. To use this on your own server, follow these steps:
 
1.    Update the PS_HOME and DAEMON_USER variables to values appropriate for your environment.
2.    Save the script as /etc/init.d/psemagent.
3.    Execute chmod +x /etc/init.d/psemagent to set the executable bit.
4.    Run chkconfig psemagent on or insserv psemagent (depends on OS).
image
image
image
image
Additional EMF Agent Command Line Parameters
The EMF agent StartAgent program accepts an optional command as a single command line parameter. Table 6-1 contains a listing of valid StartAgent commands.
image
TABLE 6-1.   EMF Agent Commands
The following listing demonstrates how to use each StartAgent command:
image
image
Using the EMF Viewer
The EMF Viewer is an HTML container that uses Extensible Stylesheet Language (XSL) to display information about agents registered with the EMF hub. Before viewing agent information, connect to your EMF hub and run the command GetEnvInfo. On Microsoft Windows run the following:
image
For all other operating systems, run the following:
image
image NOTE
The GetEnvInfo command must be run from the EMF hub. For security reasons, this command connects to the loopback address only.
When run, GetEnvInfo will prompt for the EMF hub listening port. The port number should match the port you used when updating each agent’s configuration.properties file. Here is an example of running GetEnvInfo.sh:
image
The output of the GetEnvInfo command tells me that it generated the appropriate viewer files in /opt/oracle/psft/pt/tools/PSEMAgent/envmetadata/data/. To view the environment details, I will need a web browser with access to the viewer.html file stored in the directory /opt/oracle/psft/pt/tools/PSEMAgent/envmetadata/data/. Considering that this is a headless server with no web browser, I have a couple of options:
 
■   Copy the files to my local workstation for viewing.
■   Create a Samba share and open the files locally through that share.
■   Expose the /opt/oracle/psft/pt/tools/PSEMAgent/envmetadata/data/ directory to my intranet through a web server.
 
I chose the third option so that I could configure this once, and then ignore it. To view the file, I installed Apache 2, linked the data directory into my web server, and then secured the directory using the appropriate Apache configuration directives. With my Apache web server running, I was able to use Internet Explorer to browse to http://fscm912pt/PSEMHUB/viewer.html to see agent details. Figure 6-1 shows my environment details.
image
FIGURE 6-1.   The EMF Viewer details
Securing EMF
The EMF hub uses plain HTTP connections—no encryption and no authentication. Figure 6-2 shows the information available to anyone with access to the PIA instance running the EMF hub. If you consider this information confidential, you may want to take precautions to secure this URL.
image
FIGURE 6-2.   EMF hub registered hosts
Networking, configuration, and architecture design offer a variety of ways to secure EMF. Even though the EMF does not support encryption, it is possible to encrypt agent/hub communication through the use of Secure Shell (SSH) tunnels or a combination of Secure Sockets Layer (SSL) proxies and SSL terminators. Because most Linux and UNIX servers already have an SSH daemon and client, SSH tunneling is trivial. Tunneling allows a client to communicate with a server over an encrypted channel (the tunnel). The server sees the traffic as local, allowing the client to access resources as if the client were running within the context of the server. This allows an administrator to bind services to the loopback network address, effectively hiding those services from the outside world. The first step in securing an EMF hub, therefore, is to reconfigure a standalone EMF hub to listen on the loopback address. If you’re using Tomcat, edit the conf/server.xml file found in the Tomcat installation directory. Search for the HTTP/1.1 Connector. The Connector’s XML will resemble this:
image
To cause Tomcat to listen on the loopback interface only, specify the loopback address as a new attribute in the Connector element as follows, and then restart Tomcat:
image
With Tomcat restarted and the EMF hub listening for local EMF agents only, your remote agent pings should fail. Likewise, external requests to view the Registered Hosts Summary web page at http://your.hub.server/PSEMHUB/hub should fail. So that remote agents may continue connecting to the EMF hub, create an SSH tunnel for each computer running an agent, and then configure each agent to connect over the SSH tunnel. For example, use the following command to create a tunnel to an EMF hub running on server fscm912pt and listening on port 8080:
image
The first 8080 tells SSH to forward requests for the local port 8080 to localhost:8080 on server fscm912pt. The first port number is arbitrary. The only requirement is that nothing else is using that port number. The second port number (the one following the colon) is the port on which the target service is running.
Windows clients can create SSH tunnels by using applications such as PuTTY and Plink. The following example shows how to create an SSH tunnel to server fscm912pt using the Plink SSH client:
image
After establishing the tunnel, open a browser and validate the configuration by attempting to connect to the PSEMHUB web application through the URL http://localhost:8080/PSEMHUB/hub. If all is well, edit the PSEMAgent/envmetadata/config/configuration.properties and change the hubURL property to http://localhost:8080/PSEMHUB/hub. In the scenario described here, all requests for localhost:8080 are forwarded to fscm912pt:8080 over an encrypted channel.
image
image NOTE
Even though my SSH tunnel has been up and active for far longer than any laptop should remain online, SSH tunnels are not known for reliability. SSH tunnels are demonstrated here because of their simplicity and ubiquity. Alternatives include stunnel, autossh, and SSL proxy/termination.
Database Cloning Considerations
The EMF hub identifies application instances by a Globally Unique Identifier (GUID). To generate a new GUID for a database, follow these steps:
 
1.    Stop any active web servers, application servers, and process scheduler servers.
2.    Erase the existing GUID using SQL similar to the following:
image
3.    Restart the application server.
4.    Verify that the PSOPTIONS table contains a new GUID using a query similar to the following:
image
Conclusion
The PeopleSoft Environment Management Framework is a prerequisite for Change Assistant. With the EMF configured and secure, we can move on to installing and using Change Assistant.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset