7 Advanced Management Console Agent Installation and Configuration

The Advanced Management Console agent runs as a native service with the operating systems (Windows as well as OS X) on a client desktop. The agent finds all the installed Java Runtime Environments (JREs), and then enables and automatically configures Java Usage Tracker. In an enterprise network, the agent enables the Java Usage Tracker on agent-managed desktops. At system startup, the agent reports the data on the Advanced Management Console client. The agent periodically reports data (operating system family, version, and installed JREs) to the Advanced Management Console server. The agent downloads and applies the Deployment Rule Set to the installed JREs. It automatically enables the Java Usage Tracker on installed JREs on Windows as well as OS X operating systems.

This topic contains the following sections that describe the Advanced Management Console agent, agent bundle, agent installation, and agent distribution:

About Advanced Management Console Agent

The Advanced Management Console agent is a background service.

The Advanced Management Console agent performs the following tasks:

  • Identifies all the installed JREs on the desktop and reports the resulting list to the Advanced Management Console server.

  • Enables Java Usage Tracker for each JRE in which Java Usage Tracker is available.

  • Downloads deployment rule sets from the Advanced Management Console server and installs them on each JRE.

As the Advanced Management Console agent is not supported on Linux desktops, these desktops require additional manual Java Usage Tracker configurations. See Software Prerequisites and System Requirements for Advanced Management Console Components for the JRE versions that contain Java Usage Trackers.

The Advanced Management Console server and all its components use different protocols to communicate.

Advanced Management Console Agent Bundle

The Advanced Management Console agent bundle is specific to the Advanced Management Console server that it has been downloaded from. This agent bundle does not work with another Advanced Management Console server.

The Advanced Management Console agent is bundled as a .zip file. The bundle file is configured with the following details: Application server URL and Application server certificate chain. You can download the agent bundle from the Advanced Management Console server through the Advanced Management Console User Interface (UI). The bundle installs the agent on the desktop that must be managed by the Advanced Management Console server.

Installing Advanced Management Console Agent

The Advanced Management Console agent installation requires administrator privileges and should be performed by a system administrator.

Installing Advanced Management Console Agent on Windows

Ensure that the Advanced Management Console server is running and can be accessed by the desktop before you install the Advanced Management Console agent on a desktop.

To install the agent on Windows:

  1. Log in to the desktop computer with administrator privileges.
  2. Enter https://server:port/amcwebui in the browser. Log in to Advanced Management Console UI using administrator credentials to initialize the Advanced Management Console.
  3. On the Advanced Management Console UI, click the Configuration tab and select Agents Download.
  4. Click the link agent-bundle-win32.zip and save the bundle.

    Note:

    When you download an agent bundle, the Advanced Management Console inserts parameters, such as the application server URL and the application server certificate chain into the bundle. This restricts the agent bundle to a specific instance of the Advanced Management Console server at any given time. If you modify the URL or the certificate, then you must download the agent bundle from https://server:port/amcwebui.

  5. Wait for the MD5 values to finish computing.
  6. Open the Windows File Explorer, select the .zip file and right click to choose Extract All.

    Don’t use the Cygwin utility to extract the agent bundle. The Cygwin extract utility gives improper file permissions that prevents the agent from starting.

  7. Move the AMC_Agent directory to a location, for example, C:\Program Files (x86)\Oracle\Java AMC\ (or a directory of your choice, for example, C:\AMC_Agent). In the following steps, C:\AMC_Agent represents %AMC_DIR%, where the Advanced Management Console agent gets installed. Ensure that the contents of the folder can be accessed by privileged users only.
  8. Starting with Advanced Management Console 2.2, this is an optional step. Copy %AMC_DIR%\conf\AMCUser.properties.template to %AMC_DIR%\conf\AMCUser.properties and configure the three information values with the user's actual credentials.
  9. Open a Windows command prompt with administrator privileges. Run %AMC_DIR%\bin\AMCAgent.exe -install.

    The agent is registered with the Advanced Management Console server for the provided user credentials.

    Note:

    Ensure that the Advanced Management Console server is running and that the desktop can connect to the server. If the server is down or cannot be reached, then the agent service (starting Advanced Management Console 2.4), retries to register itself to server every one hour after first failure. The next time the agent service is started, it tries again to connect to the server.

  10. Select the Control Panel, Administrative Tools and then select Services. Check that the agent service is up and running.
  11. If the agent service doesn’t start, some log messages may also be available in Windows Event Viewer. Select Control Panel, Administrative Tools, and Event Viewer to view the logs.
  12. Log in to Advanced Management Console web UI again. Go to the Desktops page and check that the desktop is now registered with the Advanced Management Console server (using the desktop owner registered email). The desktop owner now appears as Owner in the Advanced Management Console UI.
  13. In the Advanced Management Console web UI, configure the agent proxy settings and agent intervals in the Configuration tab. See Configuring Agent Intervals. If you increase the agent intervals, then the system load is reduced. When the agent intervals are increased, automatically the communication of the agent with the Advanced Management Console server automatically decreases, thus reducing the system load.

Note:

The Advanced Management Console supports the agent on Windows 32-bit and 64-bit operating systems only. The agent-bundle-win32.zip bundle works for both 32-bit and 64-bit Windows operating systems.

Installing the Advanced Management Console Agent on OS X

You can use the bin/AMCAgent.sh script file to install as well as uninstall the Advanced Management Console on the OS X operating system. The Advanced Management Console is a launched daemon and you can start, stop, or restart using the using the launchctl command.

  1. Log in to the desktop computer with administrator privileges.
  2. Enter https://server:port/amcwebui in the browser. Log in to Advanced Management Console UI using administrator credentials to initialize the Advanced Management Console.
  3. On the Advanced Management Console UI, click the Configuration tab and select Agents Download.
  4. Click the link agent-bundle-macosx.zip and save the bundle.
  5. Wait for the MD5 values to finish computing.
  6. Open the Finder, select the .zip file, right click to select Open With and then click Archive Utility to unzip all the files. You can also double click the .zip file to open the Archive Utility to unzip the files into the current folder.
    The script file doesn’t have permissions to execute. Use the chmod command to manually set the execute permissions.
  7. Execute the AMCAgent.sh script from the command prompt using the sudo ${AMC_DIR}/bin/AMCAgent.sh -install command.
After the installation, the script copies the agent binaries to /Library/Application Support/Oracle/Java_AMC directory, the .plist file to /Library/LaunchDaemons/, and starts the daemon.

Advanced Management Console Agent Logging

The Advanced Management Console agent utilizes the Java logger to log information about tasks performed by the agent as well as any errors that are encountered.

In Windows, the log files are available in the %PROGRAMDATA%\Oracle\Java_AMC directory.  In an OS X environment, the logs are available in the /Library/Application Support/Oracle/Java_AMC directory. The logs are rotated according to a policy. Starting Advanced Management Console 2.7, the maximum size of the log files and the number of files are configurable through AMCAgent.properties. By default, the rotation uses 3 log files with a maximum size of 64K.  This means that when the first log file grows to a size of 64K, logs are directed to the second log file. When the third log becomes full, the log rotates back to the first file, overwriting any existing contents there.

Unstalling Advanced Management Console Agent

Uninstalling Advanced Management Console Agent on Windows

To uninstall the Advanced Management Console agent:

  1. Open the Windows command prompt with administrator privileges.
  2. Run %AMC_DIR%\bin\AMCAgent.exe -remove to uninstall the agent. %AMC_DIR% is the directory where the Advanced Management Console agent is installed. The agent attempts to unregister itself on the Advanced Management Console Server before uninstalling. If the Advanced Management Console Server is not reachable, this could cause the uninstallation to stall or fail. In this case, %AMC_DIR%\bin\AMCAgent.exe -forceremove can be used to force the agent to uninstall without unregistering first.
    You need to run the AMCAgent.exe -forceremove in the following scenarios:
    • If %AMC_DIR%\bin\AMCAgent.exe -remove fails to uninstall agent service, then you can run the %AMC_DIR%\bin\AMCAgent.exe -forceremove command to force uninstall the agent.

    • If the agent was never successfully registered on the server, then you need to execute AMCAgent.exe -forceremove command to uninstall the agent. The AMCAgent.exe -remove doesn’t work in such a scenario.

Uninstalling the Advanced Management Console Agent on OS X

To uninstall the agent, execute the sudo ${AMC_DIR}/bin/AMCAgent.sh -remove command.
After the agent is uninstalled, the script stops the daemon, deletes the.plist file from the following directories: /Library/LaunchDaemons/ and /Library/Application Support/Oracle/Java_AMC.

Unregistering Advanced Management Console Agents and Usage Tracker Properties

You can unregister the Advanced Management Console agents and remove all Java Usage Tracker Properties files on the Advanced Management Console server in a Windows as well as in an OS X environment.

To unregister the agents, in Windows, run bin\AMCAgent.exe -remove as an administrator. In an OS X environment, run bin/AMCAgent.sh -remove as a root.
Optionally, if you want to use the Advanced Management Console UI to unregister, then do the following:
  1. In the Advanced Management Console UI, click the Desktop tab.
  2. Ensure the following: Desktop is selected in the Display drop-down list and the Table icon is selected.
  3. In the Desktop table, select the check boxes adjacent to the desktops to select the desktops that you want to unregister.
  4. Click Other Actions and select Unregister Desktop (s).
    The Unregister Desktops confirmation dialog box is displayed.
  5. Click Confirm to unregister the desktop.
The selected desktop(s) get unregistered on the server. After the agent gets uninstalled, the agent removes all the Java Usage Tracker configuration files on the desktop.

Distributing Advanced Management Console Agent

Distribution of the Advanced Management Console agent bundle is not handled by Advanced Management Console.

You can download the Advanced Management Console agent bundle from the Advanced Management Console web UI. A Software Management System, such as Microsoft SCCM, can be used to distribute the agent bundle to desktops in your enterprise.

The Software Management System that you use must provide customized options to support Advanced Management Console secure agent distribution. This system must handle the following operations using administrator privileges:

  • Extraction of the agent bundle as described in Installing Advanced Management Console Agent on Windows. Incorrect extraction may cause improper file permissions that prevents agent from starting.

  • Configuration of the bundle based on the desktop owner's user credentials.

  • Installation of the agent using the install command.

After the agent is distributed, each desktop that receives the agent is registered with the Advanced Management Console server using the user credentials that were configured for the desktop. The agent also automatically configures Java Usage Tracker and associates the Java Usage Tracker records with the user credentials that were configured for the desktop. The agent then periodically reports data, such as operating system family and version, and installed JREs to the Advanced Management Console server.

To view the desktops that are registered with the Advanced Management Console server, log in to the Advanced Management Console web UI and click the Desktops tab.