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.

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.

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

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:
  1. 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.
  2. 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.
  3. 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:

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

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

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

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

  8. Select the Control Panel, Administrative Tools and then select Services. Check that the agent service is up and running.
  9. 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.
  10. 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.

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 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:
  1. 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.
  2. On the Advanced Management Console UI, click the Configuration tab and select Agents Download.
  3. Click the link agent-bundle-linux64.zip and save the bundle to a desired location.
  4. 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.
  5. 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.
  6. Excute the AMCAgent.sh script from the terminal using the command:
    sudo bash ${AMC_DIR}/bin/AMCAgent.sh -install 
    
  7. 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:
  1. 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.
  2. 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.

  3. Click the link agent-bundle-macosx.zip and save the bundle.
  4. 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.
  5. 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.
  6. 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.
  7. Execute the AMCAgent.sh script from the terminal using the command:
    sudo ${AMC_DIR}/bin/AMCAgent.sh -install
    
  8. 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

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:
  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. 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 with the Advanced Management Console User Interface 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 agents and remove all Java Usage Tracker Properties files on the Advanced Management Console agent.

To uninstall the agent, 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 with the Advanced Management Console User Interface 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 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. 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 with the Advanced Management Console User Interface 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 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:
  1. In the Advanced Management Console UI, click the Desktop tab.
  2. Ensure that the Desktop is selected in the Display drop-down list.
    The Other Actions button is available only with the Desktop display option.
  3. Ensure that the Table icon is selected.
  4. (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.
  5. In the Desktop table, select the check boxes adjacent to the desktops that you want to unregister.
  6. Click Other Actions and then select Unregister Desktop(s) to display the Unregister Desktop(s) dialog.
  7. 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.
  8. 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.