Visit Azul.com Support

Installing AMT Discovery

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

The Discovery Tool of the Azul Migration Toolkit (AMT) scans a host and reports every Java installation it finds on disk, including one that nobody has started in years. Use it on the hosts where you don’t attach the Agent, and anywhere you want to know what is installed rather than what runs. See System Overview.

The tool only lists what is installed. Its report is a CSV file, with one row per Java installation found. When you give the tool the address of your Forwarder, it also sends the report to your installation. See Sending the Report to the Forwarder.

Before You Start

Linux macOS Windows

Package

Self-extracting installer, or an archive to unpack yourself

.pkg installer, or an archive to unpack yourself

ZIP file, no installation

Requires

Bash 4.0 or newer, and curl to send the report. The installer also needs rsync. x64, and the tool also runs on ARM64. CentOS 7, Ubuntu 18.04, and Ubuntu 24.04 are tested. Alpine isn’t supported.

The built-in Bash. Intel and Apple Silicon. macOS 12 (Monterey) or newer.

PowerShell 4.0 or newer, .NET Framework 3.5 or newer. x64, and the script Jdk-Discovery.ps1 also runs on ARM64, see the note below.

Run as

A privileged user, to see JDKs in other users' profiles

A privileged user, or a terminal with Full Disk Access

An administrator

Download the JVM Inventory package of the tool for your platform from the Azul repository. Like every other component, the download requires credentials, which you request from [email protected].

Note
 On Windows on ARM64, run the script Jdk-Discovery.ps1: the compiled amt-discovery.exe is built for x64 only. The tool doesn’t start an x64 java.exe on ARM64, so it lists x64 JDKs on such a host without their version and the values derived from it. ARM64 JDKs are reported in full.
Note
 Only the JVM Inventory package can send a report to your Forwarder. The regular Azul Migration Toolkit package scans in the same way, but when you give it a Forwarder address it prints a notice and sends nothing.
Note
 The tool sends its report over plain HTTP or HTTPS, whichever your Forwarder serves. With HTTPS, each host you scan must trust the Forwarder’s certificate. See Choosing HTTP or HTTPS.

Linux

Installing

Use the self-extracting installer, or unpack the archive into a folder yourself.

With the installer

  1. Make sure rsync is installed. The installer copies the files with it, and without it the installer installs nothing.

  2. Download amt-discovery_v<version>-sa-linux.tar.gz and unpack it. It contains the installer install_tux.

  3. Run the installer as a privileged user:

     
    sudo ./install_tux

    The installer puts the tool in /opt/azul/ams/templates/java_state_catalog and links it as /usr/bin/jdk-discovery. To remove it, run sudo ./install_tux --uninstall.

  4. Verify the installation:

     
    jdk-discovery --version

Without the installer

  1. Download amt-discovery-src_v<version>-sa-linux.tar.gz.

  2. Unpack it into a folder of your choice, for example /opt/azul/amt:

     
    sudo mkdir -p /opt/azul/amt
sudo tar zxf amt-discovery-src_v<version>-sa-linux.tar.gz -C /opt/azul/amt

  3. Verify the installation:

     
    /opt/azul/amt/jdk-discovery --version

    In the commands on this page, call the tool by this full path, or add the folder to your PATH.

Running a Scan

Run the scan as a privileged user. Replace <FORWARDER_HOST> and <PORT> with the host name or IP address of your Forwarder and its port. If your Forwarder serves HTTPS, write https:// instead of http:// (see Choosing HTTP or HTTPS):

 
sudo jdk-discovery --layout2 -m -f "$(hostname)_report.csv" --forwarder-url http://<FORWARDER_HOST>:<PORT>

The -f option names the file in which the tool saves the report. The tool sends that file to the Forwarder when the scan ends. Don’t add --stream or --notitle: a scan with either option sends nothing. See Which Scans Are Sent.

To scan several servers, run the same command on each one, for example over SSH. Every server sends its own report to the Forwarder, so you don’t need to collect the report files.

macOS

Installing

Use the .pkg installer, or unpack the archive into a folder yourself. Both put the same files in /opt/azul/amt.

With the installer

  1. Download amt-discovery_v<version>-sa-macos.pkg.

  2. Install it by double-clicking it in Finder, or from the command line:

     
    sudo installer -pkg amt-discovery_v<version>-sa-macos.pkg -target /

Without the installer

  1. Download amt-discovery_v<version>-sa-macos.tar.gz.

  2. Unpack it into /opt/azul/amt:

     
    sudo mkdir -p /opt/azul/amt
sudo tar zxf amt-discovery_v<version>-sa-macos.tar.gz -C /opt/azul/amt

Then verify the installation:

 
/opt/azul/amt/jdk-discovery --version
Note
 Add /opt/azul/amt to your PATH to call the tool as jdk-discovery from any directory.

Running a Scan

Run the scan and save the report as a CSV file. The command uses the full path, because /opt/azul/amt is not on your PATH by default. Replace <FORWARDER_HOST> and <PORT> with the host name or IP address of your Forwarder and its port. If your Forwarder serves HTTPS, write https:// instead of http:// (see Choosing HTTP or HTTPS):

 
sudo /opt/azul/amt/jdk-discovery --layout2 -m -f "$(hostname)_report.csv" --forwarder-url http://<FORWARDER_HOST>:<PORT>

The tool sends the saved file to the Forwarder when the scan ends. Don’t add --stream or --notitle: a scan with either option sends nothing. See Which Scans Are Sent.

macOS protects some locations, such as other users' home folders. To scan them without sudo, grant your terminal application Full Disk Access in System Settings > Privacy & Security > Full Disk Access. The tool writes any path it couldn’t read to a .scanlog file next to the report, so an incomplete scan is never silent.

Windows

Installing

The Windows tool needs no installation.

  1. Download amt-discovery_v<version>-sa-windows.zip.

  2. Unzip it to a folder on the host. The folder contains amt-discovery.exe, the compiled tool, and Jdk-Discovery.ps1, the same tool as a PowerShell script. It also contains Send-ForwarderReport.ps1, which sends the report to the Forwarder, and the two openjdk.*.map.win.json files. All of them must stay in the same folder as the tool.

Running a Scan

  1. Open PowerShell as an administrator.

  2. Run the scan from the folder that you unzipped. Replace <FORWARDER_HOST> and <PORT> with the host name or IP address of your Forwarder and its port. If your Forwarder serves HTTPS, write https:// instead of http:// (see Choosing HTTP or HTTPS):

     
    .\amt-discovery.exe -ReportFile "$($env:COMPUTERNAME)_report.csv" -ForwarderUrl http://<FORWARDER_HOST>:<PORT>

    To use the script instead of the executable, set the execution policy for this session first:

     
    Set-ExecutionPolicy RemoteSigned -Scope Process
.\Jdk-Discovery.ps1 -ReportFile "$($env:COMPUTERNAME)_report.csv" -ForwarderUrl http://<FORWARDER_HOST>:<PORT>

The tool writes a CSV file by default, and sends that file to the Forwarder when the scan ends. Without -ReportFile, the file is named <HOSTNAME>_report.csv. The tool sends only this default CSV report. See Which Scans Are Sent.

Sending the Report to the Forwarder

The Forwarder is how an AMT report reaches your installation. See Connecting Your Data Sources. Install and start the Forwarder first, because the tool needs its address. See Installing the Forwarder. Then give the address to the tool with this option:

Platform Option

Linux and macOS

--forwarder-url http://<FORWARDER_HOST>:<PORT>;

Windows

-ForwarderUrl http://<FORWARDER_HOST>:<PORT>;

The address is an http:// or https:// URL, or host:port, which means plain HTTP. Use the scheme that your Forwarder serves, see Choosing HTTP or HTTPS. Write the port on which your Forwarder accepts connections, which is 443 unless you changed azul.forwarder.port. Without a port, the tool uses 80 for http:// and 443 for https://. The tool sends the report in one request to /amt/report on that address. The Forwarder must run in on-premises mode (--mode=local). See Installing the Forwarder.

Choosing HTTP or HTTPS

The tool uses the scheme that your Forwarder serves. The Forwarder serves either plain HTTP or HTTPS on its port, not both, so your Agents use the same one. See Choosing HTTP or HTTPS for the Forwarder side.

HTTPS is the default of the Forwarder and the recommended setup, described below. HTTP is a deliberate opt-out for a network you trust, and the examples on this page use it because it needs no certificate. Use an http:// address, or <FORWARDER_HOST>:<PORT>, and let your Forwarder serve plain HTTP with azul.client.tls.disabled = true. Your Agents then need noSsl=true.

Warning
 With plain HTTP, the report travels unencrypted, including the machine identifiers described below. Use plain HTTP only on networks you trust.

HTTPS: use an https:// address. The tool verifies the Forwarder’s certificate against the trust store of the operating system on the host you scan. It has no option to skip that check or to use a certificate file instead. Before the first scan, make each host trust the certificate:

  • The certificate must contain the host name or IP address that you write in the address, in its Subject Alternative Names. A certificate issued for a host name doesn’t match an address written as an IP address.

  • Add the certificate of the CA that issued the Forwarder’s certificate to the trust store of each host, unless a CA that the host already trusts issued it:

    • Linux: the system CA bundle that curl uses, for example with update-ca-certificates on Ubuntu, or update-ca-trust on RedHat.

    • macOS: the System keychain, as a root trusted for SSL, for example with sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <CA_FILE>, or distributed with a configuration profile from your device management.

    • Windows: the Trusted Root Certification Authorities store of the computer (Local Computer), for example with certutil -addstore Root <CA_FILE>, or distributed with Group Policy. A certificate in a user’s own store isn’t seen by scans that run as SYSTEM, such as scheduled or SCCM scans.

If the address doesn’t match what the Forwarder serves, or the host doesn’t trust the certificate, the report is not delivered:

  • An https:// address fails at once, without sending the report, when the host doesn’t trust the certificate, when the certificate doesn’t contain the address, or when the Forwarder serves plain HTTP. The tool logs TLS handshake or certificate check failed and doesn’t retry.

  • An http:// address to a Forwarder that serves HTTPS gets no answer. The tool retries, and then logs that the upload failed.

In both cases the scan finishes as usual and the report stays in its file.

Which Scans Are Sent

  • Linux and macOS: a scan of the host that is saved to a report file in the default layout. The tool doesn’t send a scan that uses --stream, --notitle, --layout1, --pattern-csv, or -d (Docker containers).

  • Windows: the default CSV report. The tool doesn’t send a report that is written with -WMI, -JSON, -RDBMS, -EVTSRC, -Troubleshoot, -OmitHeaders, or a -Layout other than 4, the layout of the default report.

When the tool skips the upload, it logs the reason and the scan finishes as usual. The exception is --stream: the scan prints the report on the screen, so it prints no message about the upload either. How the rows of a report that was sent count against your allowance is described in Quota and Usage.

What the Tool Adds to the Report

Just before it sends the report, the tool adds columns to the end of every row. They identify the machine, so that your installation recognizes the same machine across scans and across the Agent. See What Makes One Record. The tool adds them to the report file itself: the file on disk is the file that was sent, and the columns stay in it when an upload fails.

Platform Columns Content

Linux

PL_1 to PL_3

The machine ID (/etc/machine-id, or /var/lib/dbus/machine-id when that file is missing or empty), the host name, and the network interfaces with their MAC addresses.

macOS

PM_1 to PM_5

The hardware UUID, the serial number, the network interfaces with their MAC addresses, the computer name, and the local host name.

Windows

PW_1 to PW_6

The hardware UUID, the Windows product ID, the machine ID, the serial number of the baseboard, the processor ID, and the serial number of the BIOS.

These columns hold identifiers of the machine, including serial numbers and MAC addresses. Treat the report file accordingly. A value that the machine doesn’t provide stays empty. A scan that sends no report collects none of these values and doesn’t add the columns.

When Something Goes Wrong

Reading the values takes up to 60 seconds, or 30 seconds on Windows. When it takes longer, the tool keeps the values it has read, leaves the rest empty, and sends the report. When it has read none, it sends the report without the columns.

A failed upload never fails the scan. The tool retries twice after a network error or a temporary error of the Forwarder, then logs a warning and ends the scan as usual. The report stays in its file.

Checking That the Report Arrived

The scan logs the result of the upload. A successful upload logs a line like this example, where attributes included means that the machine columns were added:

Forwarder upload: report accepted (HTTP 200, 844 bytes, attempt 1), attributes included

On the Forwarder side, each report is delivered as its own file, named amt.<timestamp>.csv. To check that data reaches your installation, see Checking That Data Arrives.

Next Steps

AMT reports reach your installation through a Forwarder. See Connecting Your Data Sources. To read the results, see Fleet Inventory.