Running an Environment Management Agent

This section discusses how to:

  • Run an agent.

  • Start an agent automatically in Windows.

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 PS_AGENT_HOME\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:

  1. Create a new shortcut from the desktop (right-click, New, Shortcut).

  2. In the Type the location of the item enter:

    <PS_HOME>\PSEMAgent\StartAgent.bat -u :<domainname>\<username>

    For example:

    c:\ptinstalls\pt851\PSEMAgent\StartAgent.bat -u :example.com\user

    Where the user specified has write access to PS_HOME.

    Note: When you run <PS_HOME>\PSEMAgent\StartAgent.bat -u :<domainname>\<username>, the %TEMP% directory is used. Both the user that runs the command and the "runas" user need write/execute access to the %TEMP% directory.

  3. Click Next, and enter a name for the shortcut.

  4. Use this shortcut to start the agent.

On UNIX:

  1. Log in as the user who has write access to the PS_HOME.

  2. PS_HOME/PSEMAgent/StartAgent.sh.

See Securing PS_HOME on UNIX.

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:

  1. Open a new command line window.

  2. Change directories to PS_HOME\PSEMAgent.

  3. 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.

Note: The recrawl process assumes the Environment Management agent is running. If it is not running, you may see error messages in the output. It is recommended that before running a recrawl, you make sure the agent is running.

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://192.0.2.1: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.

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 &

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:

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

  2. 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:

  1. 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

  2. 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.