Configure the discovery tool

1. In a web browser access: https://ip_address:5000, where ip_address is the IP address of the discovery tool from Deploy Discovery Tool. The discovery tool uses a self-signed certificate for HTTPS connection which results in a security warning. Choose Accept the risk and continue to continue to the discovery tool console.

2. If you're accessing the discovery tool console for the first time, create a discovery tool login password. Create a password, which you will use for future logins.

   Important

   Remember this password - there is no password recovery mechanism.

1. SSH to the discovery tool VM.

   ssh discovery@<discovery-tool-vm-ip>

2. Edit the Kerberos configuration file at /etc/krb5.conf.

   sudo nano /etc/krb5.conf

   Add the following configuration, replacing the placeholder values with your environment details.

   [libdefaults]
       default_realm = EXAMPLE.COM
       dns_lookup_realm = false
       dns_lookup_kdc = true
   
   [realms]
       EXAMPLE.COM = {
           kdc = dc01.example.com
       }
   
   [domain_realm]
       .example.com = EXAMPLE.COM
       example.com = EXAMPLE.COM

   Important

   Kerberos is case-sensitive. The realm name must be in uppercase (for example, EXAMPLE.COM, not example.com). The domain name in the [domain_realm] section must be in lowercase.

   Multiple Active Directory domains

   The discovery tool supports multiple Kerberos credentials for different Active Directory domains. Each credential authenticates independently, so you can configure multiple credentials normally and isolation is automatic.

   If you have servers in multiple domains, add entries for each realm in your /etc/krb5.conf file:

   [libdefaults]
       default_realm = DEV.COMPANY.COM
       dns_lookup_realm = false
       dns_lookup_kdc = true
   
   [realms]
       DEV.COMPANY.COM = {
           kdc = dc01.dev.company.com
       }
       PROD.COMPANY.COM = {
           kdc = dc01.prod.company.com
       }
   
   [domain_realm]
       .dev.company.com = DEV.COMPANY.COM
       dev.company.com = DEV.COMPANY.COM
       .prod.company.com = PROD.COMPANY.COM
       prod.company.com = PROD.COMPANY.COM

3. Verify that you can obtain a Kerberos ticket by running the kinit command.

   kinit username@REALM.COM

   Enter the password when prompted. If the command completes without errors, authentication succeeded.

4. Verify the ticket by running the klist command.

   klist

   The expected output is similar to the following.

   Ticket cache: FILE:/tmp/krb5cc_1000
   Default principal: username@REALM.COM
   
   Valid starting       Expires              Service principal
   01/01/2025 12:00:00  01/01/2025 22:00:00  krbtgt/REALM.COM@REALM.COM

5. Configure the discovery tool with the same case-sensitive principal that you used with kinit (for example, username@REALM.COM).

1. On the Discovery tool page, under Step 1. Configure discovery sources, choose Configure sources.

2. On the Configure discovery sources page, provide the Friendly name, vCenter FQDN/IP, Username, and Password.

3. Choose Save configuration.

   The discovery tool begins to collect vCenter information, as described in Discovered Inventory.

1. On the Discovery tool page, under Step 1. Configure discovery sources, choose Configure sources.

2. On the Configure discovery sources page, provide a friendly name, the host FQDN or IP address, the authentication type (NTLM or Kerberos), the WinRM username, and the WinRM password.

3. Choose Save configuration.

   The discovery tool begins to collect Hyper-V information, as described in Discovered inventory.

1. Navigate to the Import servers page from the Discovery tool homepage.

2. Prepare a CSV file with the following columns: hostname_or_ip (required), os_credential_name (optional), and oracle_credential_name (optional).

   • The hostname_or_ip value must be a valid IPv4 address or a fully qualified domain name (FQDN).

   • The os_credential_name value, if provided, must match the friendly name of an OS credential that you already configured (SSH, WinRM, or SNMP). Leave empty for servers where you have not yet configured an OS credential.

   • The oracle_credential_name value, if provided, must match the friendly name of an Oracle credential that you already configured.

3. Upload the CSV file. The tool validates all rows and rejects the file if any row is invalid.

1. Ssh to Discovery tool VM

2. Place the CA certificate(s) that signed your target servers' WinRM certificates into trust store directory /etc/pki/ca-trust/source/anchors/ on the discovery tool VM. For example: sudo cp winrm-ca.pem /etc/pki/ca-trust/source/anchors/winrm-ca.pem. Note: If your target servers use certificates signed by different CAs, copy all relevant CA certificates to this directory.

3. Update the certificate trust store: sudo update-ca-trust

4. Reboot the VM

5. (Optional) To verify that certificates have been successfully imported, you can run the following command. sudo trust list —filter=ca-anchors | grep -A 5 "<certificate_name>"

Enable discovery tool OS Access

1. Navigate to the Set up OS access page to provide Windows and Linux credentials.

2. Choose a protocol that you want to add credentials for.

3. Provide the required credentials for the selected protocol.

4. Select Auto-connect to enable the discovery tool to try all provided credentials on discovered servers until matching credentials are found for each server.

   See Using Auto-Connect Feature With Caution for important security recommendations regarding the auto-connect feature.

5. Choose Set up and connect.

1. On the Discovery tool page, in the sidebar, choose Database access.

2. Choose Add Oracle credential.

3. Provide the following information:

   • Friendly name – A descriptive name for this credential (for example, Oracle Production).

   • Port – The Oracle listener port (default 1521).

   • Service name – The Oracle service name for the target database.

   • Username – The Oracle service account username.

   • Password – The Oracle service account password.

   • Auto-connect – Turn on this option to try the credential against all servers in your inventory. Turn off this option to manually assign the credential to specific servers.

4. To add more credentials (for example, for different Oracle environments), choose Add Oracle credential again.

5. Choose Save and collect. The discovery tool immediately starts a full Oracle collection round for all servers in your inventory.

1. On the Discovery tool page, in the sidebar, choose Database access.

2. Choose Add SQL Server credential.

3. Provide the following information:

   • Friendly name – A descriptive name for this credential (for example, SQL Server Production).

   • Port – The SQL Server port (default 1433).

   • Username – The SQL Server login name.

   • Password – The SQL Server login password.

   • Auto-connect – Turn on to try the credential against all Windows servers in your inventory. Turn off to assign the credential to specific servers manually.

4. To add more credentials, choose Add SQL Server credential again.

5. Choose Save and collect. The discovery tool immediately starts a full SQL Server collection round for all Windows servers in your inventory.

1. On the Discovery tool page, choose Software updates in the sidebar.

2. Turn on Automatically check for software updates.

3. Make sure the discovery tool appliance has outbound internet access. No additional credentials are required to download updates.

1. When a new version is available, an Update available banner appears on the dashboard. Choose Review update.

2. On the Software updates page, review the available version and release date.

   Note

   For major version updates, Update now is disabled until you confirm three readiness checkboxes: that you have exported a backup, that you understand collection halts during the update, and that you will not power off the appliance during the update.

3. Choose Update now. The discovery tool stops collection, installs the new version, and restarts. The Software updates page shows progress through each stage.

4. When the update completes, sign in again. The discovery tool resumes collection automatically.

   Note

   If you see the banner "Update to version X failed. The appliance restored version Y" — the update failed but the discovery tool automatically restored the previous version. Your collected data is intact. Choose Open update page to retry.

   Important

   If the page shows Recovery required — the browser timed out waiting for the update to complete. Choose Reload page. If the discovery tool is still not reachable after reloading, contact support.

To update the discovery tool in place

1. Take a snapshot of the discovery tool VM. For the OVA or VHD appliance, use vSphere Client for VMware or Hyper-V Manager for Hyper-V. For a standalone Linux-installer host, use your platform's snapshot or image feature. A snapshot is the simplest way to roll back the update.

2. Access the discovery tool VM through your hypervisor console, or through SSH after you run enablessh. For more information, see Accessing the discovery tool VM.

3. Get the latest installer script onto the VM, and make it executable. Choose one of the following:

   • If the VM has outbound internet access, download it directly:

     curl -O https://s3.us-east-1.amazonaws.com/atx.discovery.collector.bundle/releases/latest/AWS-Transform-discovery-tool.sh

   • If the VM has no outbound internet access (for example, an air-gapped appliance), download the installer script on a machine that does have internet access, and then transfer it over SSH into the home directory of the discovery tool service user on the VM. If SSH access is disabled, first run enablessh on the discovery tool VM (see Accessing the discovery tool VM).

   chmod +x AWS-Transform-discovery-tool.sh

4. Stop the discovery tool service so that the backup in the next step captures a consistent snapshot of the database.

   sudo ./AWS-Transform-discovery-tool.sh stop

5. Back up the discovery tool application, its service files, and the data directory, so that you can roll back without a snapshot if you need to. The following Bash script reads the data directory from the service's own configuration, so it works whether you are on the standard OVA or VHD appliance or a standalone Linux-installer host:

   SVC=discovery-tool.service
   DATA_DIR=$(systemctl show -p Environment "$SVC" | sed 's/^Environment=//' | tr ' ' '\n' | sed -n 's/^DT_DATA_DIR=//p')
   if [ -z "$DATA_DIR" ]; then
     SVC_USER=$(systemctl show -p User "$SVC" | sed 's/^User=//')
     DATA_DIR="$(getent passwd "$SVC_USER" | cut -d: -f6)/.local/share/DiscoveryTool"
   fi
   DATA_DIR="${DATA_DIR%/}"
   echo "Discovery Tool data directory: $DATA_DIR"
   if [ ! -d "$DATA_DIR" ]; then
     echo "ERROR: data dir not found - do NOT proceed"
   else
     BACKUP="$HOME/discovery-tool-backup-$(date +%F).tar.gz"
     if sudo tar czf "$BACKUP" /opt/discovery-tool /etc/systemd/system/discovery-tool* "$DATA_DIR"; then
       echo "Backup created: $BACKUP ($(du -h "$BACKUP" | cut -f1))"
     else
       echo "ERROR: backup failed - do NOT proceed with the update"
     fi
   fi

   The installer keeps the database encryption key. It does not change the key during an update.

6. Run the installer. It detects the existing installation and updates it in place, keeping your data directory, encryption key, and service user. The --install-deps flag installs any system packages that the new version requires and that are not already present, using your OS package manager (yum, dnf, apt-get, or zypper).

   Note

   On an update, the installer always installs required system packages regardless of whether you pass --install-deps. This step only reaches out to your OS package repository if a required package is missing; it does not need network access if your appliance already has the required packages installed, which is typically the case on an appliance that is already running. If a package manager call does need network access and your appliance has none, host the packages in a local or mirrored repository that your package manager is configured to use, or install the missing packages manually before you run the installer.

   sudo ./AWS-Transform-discovery-tool.sh install --install-deps

7. Start the discovery tool service.

   sudo ./AWS-Transform-discovery-tool.sh start

8. Verify the update. Open https://ip_address:5000 in a web browser, sign in, and confirm that the version is updated and that your discovery sources, credentials, and inventory are present.

To roll back from the backup

1. Access the discovery tool VM as the user who created the backup, and change to the directory that contains the installer script.

2. Stop the discovery tool service.

   sudo ./AWS-Transform-discovery-tool.sh stop

3. Remove the updated application, service files, and data directory, and then restore them from the backup. Replace YYYY-MM-DD with the date in your backup file name. The script looks for the backup file in your home directory, where the backup step saved it. If you moved the backup file, change the BACKUP path in the script to the file's location.

   Warning

   This step permanently deletes the current application, service files, and data directory before it restores them from the backup. The script checks the backup first and stops without deleting anything if the backup is missing, unreadable, or doesn't contain the application, the service file, and the data directory. If you are not sure that your backup is good, revert to a VM snapshot instead.

   SVC=discovery-tool.service
   DATA_DIR=$(systemctl show -p Environment "$SVC" | sed 's/^Environment=//' | tr ' ' '\n' | sed -n 's/^DT_DATA_DIR=//p')
   if [ -z "$DATA_DIR" ]; then
     SVC_USER=$(systemctl show -p User "$SVC" | sed 's/^User=//')
     DATA_DIR="$(getent passwd "$SVC_USER" | cut -d: -f6)/.local/share/DiscoveryTool"
   fi
   DATA_DIR="${DATA_DIR%/}"
   BACKUP="$HOME/discovery-tool-backup-YYYY-MM-DD.tar.gz"
   CONTENTS=$(sudo tar tzf "$BACKUP" 2>/dev/null)
   if [ $? -ne 0 ] || ! echo "$CONTENTS" | grep -q "^opt/discovery-tool/" || ! echo "$CONTENTS" | grep -q "^etc/systemd/system/discovery-tool.service$" || ! echo "$CONTENTS" | grep -q "^${DATA_DIR#/}/"; then
     echo "ERROR: backup is missing, unreadable, or incomplete - do NOT proceed"
   else
     sudo systemctl stop discovery-tool-updater.path discovery-tool-updater.service discovery-tool-updater-recover.service 2>/dev/null
     sudo rm -rf /opt/discovery-tool "$DATA_DIR" /etc/systemd/system/discovery-tool*
     if sudo tar xzf "$BACKUP" -C / && sudo systemctl daemon-reload; then
       echo "Restore complete"
     else
       echo "ERROR: restore failed - $BACKUP is unchanged. Run this step again. If it fails again, revert to your VM snapshot, or contact AWS Support."
     fi
   fi

4. Start the discovery tool service. The second command starts the self-update watcher, if your restored version has one.

   sudo systemctl start discovery-tool
   sudo systemctl start discovery-tool-updater.path 2>/dev/null

5. Open https://ip_address:5000 in a web browser, sign in, and confirm that the previous version is running and that your discovery sources, credentials, and inventory are present. The console can take up to a minute to become available after the service starts.

To redeploy the discovery tool from a new image

1. Download the latest image file: the OVA for VMware or the VHD for Hyper-V.

2. (Optional) Delete the previous discovery tool image file before you deploy the latest one.

3. Deploy the new version. For VMware, see Deploy on VMware. For Hyper-V, see Deploy on Hyper-V.

4. Configure your discovery sources, credentials, and server imports again on the new VM.