Chapter 5
Uninstalling the Agent

When you install the J2EE Policy Agent, an uninstallation program is created in the installation directory. Using this uninstallation program, you can remove the agent from your system, if required. While the uninstallation program deletes all the installed files from your system, certain files such as resource files and audit log messages are not deleted.

This chapter describes in detail how to use the agent uninstallation program. Topics covered in this chapter include:

Pre-Uninstallation Tasks

The following tasks must be performed before you begin uninstalling the agent from your system.

Undeploy any protected application(s) from your application server. Refer to the documentation provided with your application server for details on how this can be done.

Restore the deployment descriptors of these applications by their original deployment descriptors.

Having done the above tasks, you must follow the pre-uninstallation tasks specific to your agent covered in these sections. Subsequently, you can move to the section Launching the Uninstallation Program for steps to uninstall the agent.

Agent for Sun ONE Application Server 7.0

Before you begin the uninstallation of the agent for Sun ONE Application Server 7.0, you must make sure that:

The administration server for the instance of application server where the agent is installed is running

The application server instance being protected by the agent is shut down.

Agent for BEA WebLogic Server 6.1 SP2

Before you begin uninstalling the agent for BEA WebLogic Server 6.1 SP2, you must first manually remove the agent realm that was configured after the installation of this agent. This can be done using the following steps:

Note

This section outlines the steps necessary to successfully remove the agent realm from the WebLogic Server. It must be noted that the information provided in this section is only to facilitate the removal of agent realm and should not be taken as a substitute for the information provided in WebLogic Server documents. For a complete in-depth discussion on WebLogic Custom Realms, refer WebLogic Server documentation at: http://www.bea.com.

Selecting a Different Caching Realm

Log on to the BEA WebLogic Administration console.

Click on the Security node on the left hand menu. The console displays the current security configuration on the right side content pane.

In the right content pane, click on the Filerealm tab. In the form that is now displayed, select any caching realm other than Agent Caching Realm from the drop down menu labeled Caching Realm.

Click on the Apply button and restart the Application Server.

Removing the Agent Caching Realm

Log on to the Administration Console.

Navigate to the node Security > Caching Realms on the left hand menu. This displays a list of configured caching realms on the right side.

From the list of displayed caching realms on the right side, click on the delete icon next to the Agent Caching Realm. When prompted to confirm your action, click the Yes button.

Restart the Application Server.

Removing the Agent Realm

Log on to the BEA WebLogic Administration console.

Navigate to the node Security > Realms on the left hand menu. This displays a list of configured realms on the right side.

From the list of displayed realms on the right side, click on the delete icon next to the agent realm. When prompted to confirm your action, click the Yes button.

Restart the Application Server.

The agent realm is now removed from the WebLogic Server configuration.

Once the above steps are complete, you must shutdown the BEA WebLogic Server before launching the agent uninstallation program.

Agent for BEA WebLogic Server 7.0 SP2/8.1

Before you begin uninstalling the agent for BEA WebLogic Server 7.0 SP2 or BEA WebLogic Server 8.1, you must first manually remove the Agent Authentication Provider that was configured after the installation of this agent. This can be done using the following steps:

Note

This section outlines the steps necessary to successfully remove the Agent Authentication Provider from the WebLogic Server. It must be noted that the information provided in this section is only to facilitate the removal of Agent Authentication Provider and should not be taken as a substitute for the information provided in WebLogic Server documents. For a complete in-depth discussion on WebLogic Custom Realms, refer WebLogic Server documentation at: http://www.bea.com.

Logon to the WebLogic Server console.

On the left frame, click on agentdomain > Security > Realms > myrealm, where agentdomain is the domain you had configured.

On the right frame, click on the Providers tab.

Click on Authentication.

Look for Agent Authenticator and click the Delete icon next to it.

Confirm the delete by clicking Yes.

If the DefaultAuthenticator is the only other authentication provider, change its control flag to REQUIRED. Click Apply.

Restart the server. The Agent Authentication Provider is now removed from the WebLogic Server configuration.

Once these steps are complete, you must shutdown the BEA WebLogic Server before launching the agent uninstallation program.

Agent for IBM WebSphere 5.0/5.1

Before you launch the uninstallation program for the agent for IBM WebSphere 5.0/5.1 Application Server, you must ensure that the WebSphere Application Server instance is running and the Administration application has been deployed on this server.

Agent for PeopleSoft 8.3/8.4/8.8

Before you launch the uninstallation program for the agent for PeopleSoft 8.3/8.4/8.8, you must make sure that all PeopleSoft processes have been shutdown including any front-end web server processes as applicable to your configuration.

Agents for Oracle 9iAS R2 and Oracle 10g

Stop all processes related to Oracle 9iAS R2 or Oracle 10g before uninstalling the agent. To learn more about stopping these processes, refer to the Administration Guides at the following URLs:

Before you launch the uninstallation program for the agent for SAP Enterprise Portal 6.0 SP2 and Web Application Server 6.20 SP1, you must shut down the SAP server completely. If any agent protected applications are deployed on the Web Application server, remove them from the server before you shut the server down. In order to restore these applications to their original state, perform the restoration procedures as follows:

Restore Deployment Descriptors

This step is not applicable if you do not have any agent protected applications deployed on the SAP Web Application Server.

In order to fully restore your applications to their original state before agent installation, you must undo the changes done in the post-installation steps outlined in "Post-Installation Tasks". Perform the following:

If any changes were made to enable web-tier declarative security in the web.xml deployment descriptor for your application during agent installation, manually change the deployment descriptor back to its original state in order to fully restore the application.

Restore Library References

During the agent installation, a reference to the AmSAPAgent library was added for every protected application in thelibrary.txt file located in the following directory:

base-instancedir/cluster/server/managers

In order to restore the system to its original state, edit this file and remove all the references to the AmSAPAgent library that were manually added during the agent installation.

Agent for BEA WebLogic 8.1 SP2/SP3 Server/Portal

Before you uninstall the agent for BEA WebLogic 8.1 Server/Portal, manually remove the agent authentication provider that was configured after the installation of the agent. Remove the provider by performing the following steps:

Note

This section outlines the steps necessary to successfully remove the agent authentication provider from the WebLogic 8.1 Server/Portal. Note that the information provided in this section is only to facilitate the removal of the agent authentication provider and should not be taken as a substitute for the information provided in WebLogic 8.1 Server/Portal documents. For a complete in-depth discussion on WebLogic Custom Realms, refer to WebLogic Server documentation at: http://www.bea.com

Log on to the WebLogic 8.1 Server console.

In the left frame, click agentdomain> Security> Realms> myrealm

Where agentdomain is the domain you had configured.

In the right frame, click the Providers tab.

Click Authentication.

Click the Delete icon next to Agent Authenticator.

Click Yes to confirm the deletion.

If Default Authenticator is the only other authentication provider, change its control flag to REQUIRED.

Click Apply.

Restart the server.

The agent authentication provider has now been removed from the WebLogic 8.1 Server/Portal configuration.

Shut down the WebLogic 8.1 Server/Portal domain before launching the agent uninstallation program.

Agent for Sun Java System Application Server 8.1

Before you uninstall the policy agent for Sun Java System Application Server 8.1, ensure that the following conditions apply.

The following server is running:

Domain Administration Server (DAS) for the application server instance that the agent is protecting

Preferably, the following server has been shut down (this is a standard precautionary measure):

Application Server instance that will be protected by the agent

Launching the Uninstallation Program

After completing the pre-uninstallation tasks, you are now ready to launch the uninstallation program. This uninstallation program is platform-specific and should be used in accordance with the steps outlined in this section. Once the uninstallation program has been launched successfully, you may jump to the next section which provides the necessary details on how to use this uninstallation program.

Launching the Uninstallation Program on Solaris, HP-UX, AIX and Linux

The following steps provide details on how the agent uninstallation program can be launched on Solaris, HP-UX, AIX and Red Hat Advanced Server 2.1 platforms.

Login as the root user and go to the directory where the agent is installed.

Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, you may either download and install a compatible version of this software from the Java web site http://java.sun.com or use the JDK provided along with the application server.

The uninstallation program provides two types of interfaces—a GUI or a graphical user interface, and an interactive command line interface. In most cases, the GUI uninstallation program can be used for installing the agent. However, in cases such as when you are uninstalling the agent over a telnet session on a remote server and do not have windowing capabilities, then it is recommended that you use the command-line uninstallation program for uninstalling the agent.

If you choose to use the GUI uninstallation program, then it is required that you set your DISPLAY environment variable to ensure that the GUI uninstallation program window appears on the correct console.

Once you have completed the above steps, you are now ready to execute the uninstallation script that launches the agent uninstallation program. This program can be launched in two different modes—a GUI mode which has a rich graphical interface, and an interactive terminal mode that does not require any windowing capability. The following steps may be used to launch the uninstallation program in each of these two modes.

Note

In order to launch the uninstallation program on Red Hat Advanced Server 2.1, you must have the Korn shell installed in the system. If the Korn shell is not available, you may launch the uninstallation program directly by using a Java command such as java -cp . classfilename

Launching the Uninstallation Program in the GUI Mode

To launch the uninstallation program in the GUI mode, use the following command:

#./uninstall

When launching the program in a GUI mode, it is required that you set your JAVA_HOME and DISPLAY environment variables correctly as pointed out in the previous steps. If however, you have not set these variables, the setup script will prompt you for their values accordingly. If your JAVA_HOME environment variable is not set correctly, the setup script will display the following prompt:

Enter JAVA_HOME location (Enter "." to abort):

At this prompt, you may type the full path to the JDK installation directory that should be used for launching the uninstallation program. Otherwise, enter a period (.) to abort the uninstallation.

If your DISPLAY environment variable is not set correctly, the setup script will display the following prompt:

Please enter the value of DISPLAY variable (Enter "." to abort):

At this prompt, you may specify the hostname for the DISPLAY variable. Otherwise enter a period (.) to abort the uninstallation.

Note

If you enter a value for the DISPLAY environment variable which is not appropriate, the uninstallation program window may get displayed on a different console, giving the impression that the uninstallation program is hanging. If such a condition occurs, please verify your DISPLAY environment variable by launching another graphical program such as xterm.

If the supplied value for DISPLAY environment variable is not a valid or reachable hostname, or is that of a host, which does not allow you to use its windowing capabilities, the uninstallation program will automatically shift to the interactive command line mode.

Launching the Uninstallation Program in the Command-Line Mode

To launch the uninstallation program in a non-GUI or command line mode, use the following command:

# ./uninstall -nodisplay

When launching the program in a command line mode, it is required that you set your JAVA_HOME environment variable correctly as pointed out in the previous steps. If however, you have not set this variable, the uninstallation script will prompt you for its value as follows:

Enter JAVA_HOME location (Enter "." to abort):

At this prompt, you may type the full path to the JDK installation directory that should be used for launching the uninstallation program. Otherwise, enter a period (.) to abort the uninstallation.

Depending upon the mode in which you have launched the uninstallation program, you should see the appropriate interface appear at this stage.

Note

Instead of using the provided script to launch the uninstallation program, you may alternatively invoke the uninstaller class file in the agent installation directory with a JDK runtime version 1.3.1 or above to launch the uninstallation program.

Launching the Uninstallation Program on Windows 2000

Follow these steps to launch the agent uninstallation program on Windows 2000 platform:

Log into your Windows system as a user with Administrative privileges. If you do not have administrative privileges, either log on as Administrator user or request such privileges to be granted to your account by the system administrator of the machine or domain as applicable.

Open a command prompt, and go to the directory where the agent is installed. This directory will contain the uninstall.bat file, which can be used to launch the uninstaller.

In order to use uninstall.bat to launch the uninstallation program, you must have a JDK version 1.3.1 or higher available in your system path. This can be verified by typing the following command in a command prompt window:

C:\> java -version

java version 1.3.1_02

Java(TM) 2 Runtime Environment, Standard Edition (build
1.3.1_02-b02)

Java HotSpot(TM) Client VM (build 1.3.1_02-b02, mixed mode)

Note

It is recommended that you download and install a compatible version of JDK if you do not have one on your system. Using the JDK supplied by the application server may result in malfunction of the uninstallation program and you may not be able to successfully uninstall the agent.

The program uninstall.bat may be executed by typing the file name at the command prompt window in a directory where it is present, or by double clicking the file in Windows Explorer. For example:

C:\> uninstall.bat

The uninstallation program provides two types of interfaces—a GUI and an interactive command line interface. You can launch the uninstallation program in the GUI mode by invoking uninstall.bat file from a command prompt window as shown above or by double clicking it in Windows Explorer. The uninstallation program may be launched in a command line mode by passing the argument -nodisplay to the uninstall.bat script as follows:

C:\> uninstall.bat -nodisplay

Note

Instead of using the provided scripts and executable that launch the uninstallation program, you may alternatively invoke the uninstaller class file in the agent installation directory, with a JDK runtime version 1.3.1 or above to launch the uninstallation program.

Depending upon the mode in which you have launched the uninstallation program, you should see the appropriate interface appear at this stage.

Using the Uninstallation Program

As mentioned in the last section, the agent uninstallation program provides two types of interfaces - a GUI or graphical user interface, and a non-GUI or console based interactive interface. Once the uninstallation program has been launched, you must provide all the necessary information requested by this program in order to successfully uninstall the agent on your system. The following two sections describe in detail how to use this uninstallation program in each interface to successfully uninstall the agent on your system.

Once the uninstallation program has been launched, the expected interaction will be the same on any platform for a given application server agent. Thus the steps outlined here for a certain application server agent uninstallation will be applicable to the same agent uninstallation for the same application server on a different platform.

Using the GUI Uninstallation Program

When the agent uninstallation program is launched in the GUI mode, it presents the user with a series of screens that gather the necessary information and report the status of the uninstallation progress. The agent uninstallation also provides active feedback, by means of pop-up dialog boxes that contain the necessary help or error messages, to help the user enter correct information in case the provided information is not valid. Follow these steps to use the agent uninstallation program in the GUI mode.

Note

The information regarding the use of the agent uninstallation program as outlined in this section is applicable to all application server agents supported in this release. Any agent-specific differences have been identified here separately.

Launch the uninstallation program as explained in the earlier sections. The uninstallation program begins with a welcome screen.

Read the information provided in this screen.

Click Next to continue. The screen that follows is specific to the application server agent that is being uninstalled. Please jump to the appropriate section from the following list depending on which application server agent is being uninstalled.

When uninstalling any agent for which the option to install JCE or JSSE libraries was selected during installation, make sure that the uninstallation program uses a JDK other than the one using which these libraries were installed. This is because, if the uninstallation program is using the same JDK, it may not successfully remove the JCE and JSSE libraries.

Agent for Sun ONE Application Server 7.0

In the following screen enter information about the Sun ONE Application Server 7.0 instance, on which the agent is installed.

Figure 5-1 Sun ONE Application Server Uninstallation screen

Admin Server Port: Enter the port number on which the Administration Server for this Sun ONE Application Server 7.0 is available.

Admin User Name: Enter the user name of the Administrator of this Sun ONE Application Server 7.0 instance.

Enter Admin Password: Enter the password for the Administrator of this Sun ONE Application Server 7.0 instance.

Re-enter Admin Password: Re-enter the password for the Administrator of this Sun ONE Application Server 7.0 instance.

Note

You must ensure that the Sun ONE Application Server 7.0 Administration Server is running at the time of uninstallation of the agent. Also ensure that the application server instance on which the agent is installed is shutdown.

Agent for IBM WebSphere Application Server 5.0/5.1

In this screen, enter information about the WebSphere Application Server 5.0/5.1 instance, on which the agent is installed.

Figure 5-2 WebSphere Application Server Uninstallation screen

WebSphere Admin Connector: Specify the protocol for connecting to WebSphere Administration Service. You can choose between SOAP and RMI.

amldapuser Password: Enter the password assigned to the amldapuser as specified during Sun ONE Identity Server installation.

Re-enter amldapuser Password: Re-enter the amldapuser password in this field to ensure that the correct value is used by the agent.

Note

You must ensure that the IBM WebSphere Application Server 5.0/5.1 instance is running at the time of uninstallation of the agent.

The uninstallation program now checks for the used disk space and displays the Ready to Uninstall screen.

Click the Uninstall Now button to start the uninstallation of the agent on your system.

The next screen displays the progress of uninstallation as the uninstallation program makes changes to your system. This screen does not require any user input or action and will automatically proceed to the next screen when the uninstallation program finishes making the necessary changes to your system.

The next screen displays the uninstallation summary. The uninstallation program displays the status of the uninstallation in this screen. You may click on the Details button to see more information on the actions that were performed by the uninstallation program.

The agent has now been removed from your system You may wish to restart the application server and ensure that it is back to its original state and is fully function.

Note

The uninstallation program for the IBM WebSphere Application Server 5.0/5.1 agent stops the IBM WebSphere Application Server at the end of the uninstallation. You may manually restart it later.

Agent for Sun Java Systems Application Server 8.1

If you are uninstalling the agent for Sun Java System Application Server 8.1, enter the configuration information on the screen as explained in this section.

Enter Admin Password:
Enter the Administrator password for the domain. The password is defined as AS_ADMIN_PASSWORD in the password file.

Re-enter Admin Password:
Re-enter the Administrator password for the domain.

Using the Command Line Uninstallation Program

The uninstallation program consists of one or more message screens that provide the user with information and let the user enter preferences that determine how Sun ONE Identity Server Policy Agent is uninstalled. Some questions require more detailed information that the user may be required to type. The question may have a default value that is displayed inside of brackets []. The default answer can be accepted by, pressing the Enter key. If a different answer needs to be provided, it can be typed at the command prompt.

The agent uninstallation program also provides active feedback to help the user enter correct information in case the provided information is not valid by means of necessary help or error messages. Follow these steps to use the agent uninstallation program in the command line mode.

Note

The information regarding the use of the agent uninstallation program as outlined in this section is applicable to all application server agents supported in this release. Any agent-specific differences have been identified here separately.

Launch the uninstallation program in the nodisplay mode, from the agent installation directory. The uninstallation program begins with a welcome message.

Read the information provided on this screen and press Enter to continue.

The questions that follow are specific to the application server agent that is being uninstalled. Please jump to the appropriate section from the following list depending on which application server agent is being installed.

There is no application server specific question for BEA WebLogic Server and PeopleSoft agent uninstallation programs. If you are uninstalling these agents, please jump to the next step directly.

When uninstalling the agent for BEA WebLogic Server 6.1 SP2, make sure that the uninstallation program uses a JDK other than the one supplied with BEA WebLogic Server 6.1 SP2. This is because, if the uninstallation program is using the JDK provided with BEA WebLogic Server 6.1 SP2, it does not remove the JCE and JSSE libraries.

Agent for Sun ONE Application Server 7.0

At the prompts, enter information about the Sun ONE Application Server 7.0 instance, on which the agent is installed.

Note

You must ensure that the Sun ONE Application Server 7.0 Administration Server is available at the time of uninstallation of the agent. Also ensure that the application server instance on which the agent is installed is shutdown.

In the Ready to Uninstall screen, enter 1 to start the uninstallation of the agent. Enter 2 to restart the uninstallation process from the beginning and enter 3 if you want to exit the uninstallation program.

The next screen displays the progress of uninstallation as the uninstallation program makes changes to your system. This screen does not require any user input or action and will automatically proceed to the next screen when the uninstallation program finishes making the necessary changes to your system.

Uninstalling Sun ONE Identity Server Policy Agent

|-1%----------25%-------------50%-------------75%----------100%|

The next screen displays the uninstallation summary as follows. The uninstallation program displays the status of the uninstallation in this screen. You can enter 1 to see more information on the actions that were performed by the uninstallation program.

Uninstallation Details:

Product Result More Information

1. Sun ONE Identity Server Policy Agent Full Available

2. Done

Enter the number corresponding to the desired selection for more
information, or enter 2 to continue [2] {"!" exits}:

The agent has now been removed from your system. You may restart the application server and ensure that it is back to its original state and is fully functional.

Note

The uninstallation program for the IBM WebSphere Application Server 5.0/5.1 agent stops the IBM WebSphere Application Server at the end of the uninstallation. You may manually restart it later.

Agent for Sun Java Systems Application Server 8.1

At the prompts, enter information about the Sun Java System Application Server 8.1 instance, on which the agent is installed as shown in the table and explanations that follow.

Admin Server Host [arth] {"<" goes back, "!" exits}

Admin Server Host is Remote [false] {"<" goes back, "!" exits}?

Admin Server Port [4849] {"<" goes back, "!" exits}

Admin Server Protocol [https] {"<" goes back, "!" exits}

Admin User Name [admin] {"<" goes back, "!" exits}

Enter Admin Password [] {"<" goes back, "!" exits}

Re-enter Admin Password [] {"<" goes back, "!" exits}

Admin Server Host:
Enter the host on which the Domain Administration Server for this instance is running.

Admin Server Host is Remote:
Enable this field only if the Domain Administration Server for this instance is not on the local host where the instance is running.

Admin Server Port:
Enter the port number on which the Domain Administration Server for this instance is available.

Admin Server Protocol:
Select the appropriate protocol of the Domain Administration Server. This protocol value may either be HTTP or HTTPS.

Enter Admin Password:
Enter the administrator password for the domain. The password is defined as AS_ADMIN_PASSWORD in the password file.

Re-enter Admin Password:
Re-enter the Administrator password for the domain.

Note

For instances where DAS is not on the agent host, therefore DAS is remote, undo the post-installation tasks that were completed after installation as described in the Post-Installation Tasks section of Chapter 2, specifically in "Agent for Sun Java System Application Server 8.1."

Post-Uninstallation Tasks

The following agents require certain post-uninstallation tasks to be performed before the system is restored to its original state:

Agent for SAP Enterprise Portal 6.0SP2

When the agent for SAP Enterprise Portal is uninstalled, it modifies various files in the SAP Enterprise Portal installation and takes backups where necessary. When the agent uninstallation program requires multiple changes to a particular file, it may result in more than one backup being made depending upon the uninstallation requirements.

These generated backup files can be easily identified by their suffix of the form -Agent-timestamp. For example if a file named sample.xml is being modified by the uninstallation program on 03/24/04, it may create a backup such as sample.xml-Agent-20040325.

It is recommended that these sample files be removed from their respective directories and copied to another location outside of the server directory before the SAP Enterprise Portal is started for the first time after the uninstallation of the agent. This is necessary to ensure that no backup file is mistaken for a configuration file by the SAP Enterprise Portal runtime. Moreover, even though the files left behind are harmless, they can cause clutter in the long run and can be difficult to remove if the SAP Enterprise Portal has marked them for being stored in its database.

These files are located in the following directories. The variable base_instance_dir referred here denotes the directory where the server instance is located.

When the agent for SAP Enterprise Portal and Web Application Server is uninstalled, it modifies various files in the SAP Enterprise Portal installation and/or Web Application Server installation and takes backups where necessary. When the agent uninstallation program requires multiple changes to a particular file, the result might be more than one backup being made depending upon the uninstallation requirements.

These generated backup files can be easily identified by their suffix of the form: -Agent-timestamp

For example if a file named sample.xml is modified by the uninstallation program on 11/24/04, it might create a backup such as sample.xml-Agent-20040325.

Remove these backup files from their respective directories and copy them to another location outside of the server directory before the SAP Enterprise Portal or Web Application Server is started for the first time after the uninstallation of the agent.

This removal process is necessary to ensure that no backup files are mistaken for configuration files by the SAP runtime. Moreover, even though the files left behind are harmless, they can cause clutter in the long run and can be difficult to remove if the SAP runtime has marked them for being stored in its database.

These backup files are located in the following directories. Where base_instance_dir refers to the directory in which the server instance is located: