Advanced Management Console Agent Installation and Configuration

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

This topic contains the following sections:

Configuring the Agent Proxy and the Agent Intervals

The agent proxy server is included in the bundle. If the bundle is already downloaded and the proxy is changed later, the bundle will not contain the proxy settings.

To configure the agent proxy and the agent intervals:

Enter https://server:port/amcwebui in the browser and log in to the Advanced Management Console UI by using administrator credentials to initialize the Advanced Management Console. See Initializing Advanced Management Console.
Configure the agent proxy server host and port.

Note:

Step 2 must be completed before the agent bundle is downloaded. If a proxy server is required to access the AMC Server, then the agent would not be able to reach the server to register without this information.
1. In the Advanced Management Console UI, click the Configuration tab.
2. Click Agents Download.
3. Click Edit to display the Configure AMC Agent Proxy Settings dialog.
4. Enter the following details for the agent to connect to the Advanced Management Console server:
  - Agent Proxy Host Name: Specify a proxy server host name.
  - Agent Proxy Port: Specify a proxy server port number.
5. Click Save.
Configure the agent intervals.

Note:
If you increase the agent intervals, then the system load is reduced. When the agent intervals are increased, the communication of the agent with the Advanced Management Console server automatically decreases, which reduces the system load.
1. Click the Configuration tab.
2. Click Agent Settings.
3. Click Edit to make the fields editable.
4. Edit any of the following values. You can either edit all of them or just the ones that you want to:
  
  JUT Processing Interval
  
  Interval for the agents to report Java Usage Tracker records to the server
  
  Check Command Interval
  
  Interval to check if the server has any commands for the agent
  
  Standard JRE Scan Interval
  
  Interval to scan Java Runtime Environment (JRE) in the standard location (For example, on Windows it is C:\Program Files\Java) and report to server
  
  Application JRE Scan Interval
  
  Interval to scan JRE under the application location (For example, on Windows it is C:\Program Files) and report to server
  
  LocalStorage JRE Scan Interval
  
  Interval to scan JREs in the entire local storage system (not targeting any particular directory) and report to server
  
  Agent Auto Update
  
  Enable or disable the agent auto update
  
  Agent Log File Max Size (Kb)
  
  Maximum agent log file size in Kb
  
  Number of Agent Log Files
  
  Maximum agent log file number during agent log rotation
  
  Randomize Interval
  
  Enable or disable randomize interval
5. Click Save.

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:

Configure the agent proxy and the agent intervals. See Configuring the Agent Proxy and the Agent Intervals.
The agent proxy server is included in the bundle. If you change the proxy server settings, you will need to download the agent bundle again and distribute the updated bundle.
On the Advanced Management Console UI, click the Configuration tab and select Agents Download.

Note:

When you select Agents Download, you might need to wait for the MD5 values to finish computing. If the bundle isn't already generated, it takes a short time to build it. Once it's shown, the bundle is ready to download.
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.
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.
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.
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.
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. Beginning with Advanced Management Console 2.4, if the server is down or cannot be reached, then the agent service tries to register itself with the server once each hour after the first failure. The next time the agent service is started, it tries again to connect to the server.
Select the Control Panel, Administrative Tools and then select Services. Check that the agent service is up and running.
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.
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.

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 Advanced Management Console Agent on macOS

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

To install the Advanced Management Console on the macOS operating system:

Configure the Agent Proxy and the Agent Intervals. See Configuring the Agent Proxy and the Agent Intervals.
The agent proxy server is included in the bundle. If you change proxy server settings, you will need to download agent bundle again and distribute the updated bundle.
On the Advanced Management Console UI, click the Configuration tab and select Agents Download.

Note:

When you select Agents Download, you might need to wait for the MD5 values to finish computing. If the bundle isn't already generated, it takes a short time to build it. Once it's shown, the bundle is ready to download.
Click the link agent-bundle-macosx.zip and save the bundle.
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.
Execute the AMCAgent.sh script from the command prompt using the command:
```
sudo ${AMC_DIR}/bin/AMCAgent.sh -install
```
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.

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 a macOS environment, the logs are available in the /Library/Application Support/Oracle/Java_AMC directory. The logs are rotated according to a policy. Beginning with 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 three 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. See Configuring the Agent Proxy and the Agent Intervals for procedures you can use to edit logging parameters.

Unstalling Advanced Management Console Agent

This topic contains the following sections that describe how to uninstall Advanced Management Console Agent:

Uninstalling the Advanced Management Console Agent on Windows

On Windows, you can run the -remove command to uninstall the Advanced Management Console agents and remove all Java Usage Tracker Properties files on the Advanced Management Console server.

To uninstall the Advanced Management Console agent:

Open the Windows command prompt with administrator privileges.
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. After the agent is unregistered on the server, all Java Usage Tracker configuration files (usagetracker.properties) on the desktop are also removed.

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.
Run the AMCAgent.exe -forceremove command in the following scenarios:
- If %AMC_DIR%\bin\AMCAgent.exe -remove fails to uninstall agent service, then 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 execute AMCAgent.exe -forceremove command to uninstall the agent. The AMCAgent.exe -remove doesn’t work in such a scenario.

After the agent is unregistered on the server, all Java Usage Tracker configuration files (usagetracker.properties) on the desktop are also removed.

Uninstalling the Advanced Management Console Agent on macOS

On macOS, you can run the -remove command to uninstall the Advanced Management Console agents and remove all Java Usage Tracker Properties files on the Advanced Management Console server.

To uninstall the agent:

Execute the command:
```
sudo ${AMC_DIR}/bin/AMCAgent.sh -remove
```
The agent attempts to unregister itself on the Advanced Management Console Server before uninstalling. After the agent is unregistered on the server, all Java Usage Tracker configuration files (usagetracker.properties) on the desktop are also removed.

If the Advanced Management Console Server is not reachable, this could cause the uninstallation to stall or fail. In this case, you can use the ${AMC_DIR}/bin/AMCAgent.sh -forceremove command to force the agent to uninstall without unregistering first.
You need to run the AMCAgent.sh -forceremove command in the following scenarios:
- If using the ${AMC_DIR}/bin/AMCAgent.sh -remove command fails to uninstall the agent service, then run the ${AMC_DIR}/bin/AMCAgent.sh -forceremove command to force uninstall the agent.
- If the agent was never successfully registered on the server, then you need to execute AMCAgent.sh -forceremove command to uninstall the agent. The AMCAgent.sh -forceremove doesn’t work in such a scenario.

After the agent is uninstalled, the agent is unregistered on the server, all Java Usage Tracker configuration files usagetracker.properties on the desktop are removed. The script stops the daemon and deletes the.plist file from the following directories:

/Library/LaunchDaemons/
/Library/Application Support/Oracle/Java_AMC

Unregistering Desktops with the Advanced Management Console User Interface

After running -remove to uninstall the Advanced Management Console agents on Windows and macOS, you can use the Advanced Management Console to remove any desktops that cannot contact the Advanced Management Console server.

To remove desktops that cannot contact the Advanced Management Console server:

In the Advanced Management Console UI, click the Desktop tab.
Ensure that the Desktop is selected in the Display drop-down list.
The Other Actions button is available only with the Desktop display option.
Ensure that the Table icon is selected.
(Optional) Set the filter criteria to show only the desktops that you want to unregister.
1. Click Add Criteria.
2. Select the filters and set the values for each filter that you select.
In the Desktop table, select the check boxes adjacent to the desktops that you want to unregister.
Click Other Actions and then select Unregister Desktop(s) to display the Unregister Desktop(s) dialog.
Select the target desktops by selecting either of the following options:
- Selected Desktops: Shows the number of desktops selected.
- All Filtered Desktops: Shows the number of filtered desktops included.
Click Confirm.
The selected desktops or all filtered desktops are unregistered.

The selected desktop(s) are unregistered on the server.

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.