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, Linux, and macOS) on a client desktop. The agent finds all the installed Java runtimes, and then enables and automatically configures Java Usage Tracker. The agent periodically reports Java usage and other data (operating system family, version, and installed Java runtimes) to the AMC server. The agent downloads and applies the Deployment Rule Set.

This topic contains the following sections that describe the AMC 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 Java runtimes on the desktop and reports the resulting list to the Advanced Management Console server.
Enables Java Usage Tracker for each Java runtime in which Java Usage Tracker is available.
Reports the usage of Java applications and Java runtimes to the server.
Downloads deployment rule sets from the AMC server and installs them on a client desktop.
Allows installation and uninstallation of Oracle Java runtimes (JRE or JDK) on Windows and macOS platforms.

Advanced Management Console supports Windows, macOS, and Linux distributions (with systemd or upstart service management framework). See Software Prerequisites and System Requirements for Advanced Management Console Components for details. For platforms that are not supported, the Java Usage Tracker can be configured manually.

Advanced Management Console Agent Bundle

The Advanced Management Console agent is bundled as a .zip file.

The bundle file is configured with Application server URL and Application server certificate chain details. 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.

The Advanced Management Console agent bundle is configured to the Advanced Management Console server that it has been downloaded from.

Note:

If multiple agents from different servers are installed on the same machine, then the earlier configurations will be overwritten by the latest agent installation. The system is configured to communicate with the server from which the latest agent bundle was downloaded.

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 AMC UI by using administrator credentials to initialize the AMC. 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 AMC 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 SHA256 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 required bundle link, either agent-bundle-win32.zip or agent-bundle-win64.zip and save the bundle.
Note:
- The agent-bundle-win32.zip bundle should be used for agent installations on 32-bit Windows platform. 32-bit support for Advanced Management Console agent is provided only for Windows operating systems.
- 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 AMC 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. If the user's credentials were configured in step 6, then the desktop owner now appears as Owner in the Advanced Management Console UI.

Installing Advanced Management Console Agent on Linux

You can use the bin/AMCAgent.sh script file to install and uninstall the Advanced Management Console agent on the Linux operating system. The Advanced Management Console agent is a native service that you can start, stop, or restart from the Linux terminal.

To install the Advanced Management Console agent on the Linux 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.
Click the link agent-bundle-linux64.zip and save the bundle to a desired location.
Start a Linux terminal. Goto the folder where the zip file was downloaded. Extract the zip. In the following steps, ${AMC_DIR} represents the AMC_Agent directory where the Java Advance Management Agent files are extracted.
Starting with Advanced Management Console 2.2, this is an optional step. Rename ${AMC_DIR}/conf/AMCUser.properties.template to ${AMC_DIR}/conf/AMCUser.properties and configure the three information values with the user's actual credentials.
Excute the AMCAgent.sh script from the terminal using the command:
```
sudo bash ${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. If the user's credentials were configured in step 5, then the desktop owner now appears as Owner in the Advanced Management Console UI.

As part of the installation, the script copies the agent binaries to /usr/local/Oracle/Java_AMC directory and starts the daemon. It also registers the native service by placing the registration file in /etc/systemd/system/ or /etc/init/ directories for systemd or upstart frameworks respectively.

Installing Advanced Management Console Agent on macOS

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

To install the Advanced Management Console agent 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 SHA256 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.
The files get extracted to AMC_Agent directory within the current folder. In the following steps, ${AMC_DIR} represents the AMC_Agent directory where the Java Advance Management Agent files are extracted.
Starting with Advanced Management Console 2.2, this is an optional step. Rename ${AMC_DIR}/conf/AMCUser.properties.template to ${AMC_DIR}/conf/AMCUser.properties and configure the three information values with the user's actual credentials.
Execute the AMCAgent.sh script from the terminal using the command:
```
sudo ${AMC_DIR}/bin/AMCAgent.sh -install
```
A dialog appears stating that the AMCAgent app is downloaded. Click Open.
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. If the user's credentials were configured in step 6, then 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.

The log files are available in the following directory:

Windows: %PROGRAMDATA%\Oracle\Java_AMC
macOS: /Library/Application Support/Oracle/Java_AMC
Linux: /usr/local/Oracle/Java_AMC/

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 agent and remove all Java Usage Tracker Properties files from the desktop.

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. However, AMCAgent.exe -forceremove does not perform the cleanup of usagetracker.properties files.
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.
Note:
See Unregistering Desktops to unregister the agent from the User Interface.

Uninstalling the Advanced Management Console Agent on Linux

On Linux, you can run the remove command to uninstall the Advanced Management Console agent and remove all Java Usage Tracker Properties files from the desktop.

To uninstall the agent, open the Linux terminal and execute the command:

sudo bash ${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 sudo bash ${AMC_DIR}/bin/AMCAgent.sh -forceremove command to force the agent to uninstall without unregistering first. However, AMCAgent.exe -forceremove does not perform the cleanup of usagetracker.properties files.

You need to run the AMCAgent.sh -forceremove command in the following scenarios:

If using the AMCAgent.sh -remove command fails to uninstall the agent service, then run the 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 -remove command doesn’t work in such a scenario.

Note:

See Unregistering Desktops to unregister the agent from the User Interface.

After the agent is uninstalled, the script stops the daemon and deletes the service registration file based on the service management framework from either:

/etc/systemd/system/
/etc/init/

Uninstalling the Advanced Management Console Agent on macOS

On macOS, you can run the remove command to uninstall the Advanced Management Console agent and remove all Java Usage Tracker Properties files from the desktop.

To uninstall the agent, open the terminal and execute the command:

sudo ${AMC_DIR}/bin/AMCAgent.sh -remove

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. However, AMCAgent.exe -forceremove does not perform the cleanup of usagetracker.properties files.

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 -remove command doesn’t work in such a scenario.

Note:

See Unregistering Desktops to unregister the agent from the User Interface.

After the agent is uninstalled, the script stops the daemon and deletes the .plist file from the following directories:

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

Unregistering Desktops

You can use the Advanced Management Console to remove any desktops that cannot contact the Advanced Management Console server.

Follow these steps to remove the 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

In an enterprise environment, deploying Advanced Management Console agent requires installation and configuration of AMC agent on each client desktop. Distribution of the AMC agent bundle is not handled by the Advanced Management Console and has to be taken care separately.

Consider using a desktop as a host to stage the agent bundle. From this host, distribute and install the agent bundle on multiple client desktops.

Follow these steps to install the AMC agent in multiple client desktops:

Download the Advanced Management Console agent bundle from the AMC web UI to the host desktop. To download the agent bundle, select Configuration and then Agent Download.

Note:
Ensure that you do NOT run the install command (for example, %AMC_DIR%\bin\AMCAgent.exe -install). By doing so, the host desktop will get registered as an agent with the AMC server.
For distribution of the downloaded agent bundle:
1. To distribute the agent bundle to client desktops in your enterprise, use a Software Management System (such as Microsoft SCCM). The Software Management System that you choose must be capable of providing customized options to support secure Advanced Management Console agent distribution. This system must also handle the following operations using administrator privileges:
  1. Extraction of the agent bundle. Incorrect extraction may cause improper file permissions that prevent agent from starting.
  2. Configuration of the bundle based on the client desktop owner's user credentials.
  3. Installation of the agent using the install command. See Installing Advanced Management Console Agent.
2. If the agent bundle is distributed to the client desktops through other means, ensure that extraction of bundle and installation steps are followed as described in Installing Advanced Management Console Agent.

After the agent is installed, each client desktop is registered with the Advanced Management Console server. 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 client desktops that are registered with the Advanced Management Console server, log in to the Advanced Management Console web UI and click the Desktops tab.