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

See Starting an Agent in the Background on UNIX.

See Starting an Agent With PSEMAgent Windows Service.

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.

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 System and Server Administration: 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.