Run a guest discovery

This document describes the steps to run the different guest discovery methods that the mcdc CLI provides.

Guest discovery lets you scan and collect data about the running applications on your machines, which includes both virtual machine (VM) instances and physical servers. It also collects data about the machine configuration, hardware, network, as well as open files, services, and processes.

For machines running on platforms for which the Migration Center discovery client CLI doesn't support inventory discovery, such as machines running on-premises, as well as for a full assessment of VMs running on VMware, AWS, and Azure, you can run a guest discovery. Guest discovery uses a guest collection script to collect data about the machine and writes that data to a guest collection tar file for Linux machines, or zip file for Windows machines.

The machine hosting the mcdc CLI uploads the script to the target machine, runs it, and then downloads the results. You can run the script locally on the target machine, or run it remotely. Depending on your infrastructure, you can choose to use the mcdc CLI in the following ways:

  • For Linux and Windows VMs deployed on VMware, the mcdc CLI supports remote execution with the discover vsphere command.
  • For Linux machines accessible by the mcdc CLI, you can perform a remote discovery using SSH with the discover ssh command.
  • For Windows machines accessible by the mcdc CLI, you can perform a remote discovery using Windows Management Instrumentation (WMI) with the discover wmi command.
  • For Linux and Windows machines without connection to the mcdc CLI, you can download and run the guest collection scripts locally, and then manually import the collected data to the machine that's hosting the mcdc CLI.

The guest collection script runs a series of commands to gather information about the source machine and might also collect potentially sensitive data such as command-line arguments, network information, or environment variables and arguments in running processes.

Before you begin

  1. Review the requirements for downloading and running the mcdc CLI.
  2. Review the requirements for downloading and running the guest collection scripts.
  3. Complete the steps to download mcdc CLI.

Collect data remotely using VMware tools

For VMs hosted on vSphere, the mcdc CLI can use VMware tools to deploy and run the collection scripts remotely on both Linux and Windows VMs. When using VMware tools, the mcdc CLI tool does the following:

  • Uploads the collection script to the VM.
  • Runs the script on the VM.
  • Downloads and imports the results.

Two sets of credentials are required to collect data remotely:

  • The vCenter server username passed to the mcdc CLI to connect to vSphere, which must have the following privileges on the VM:
    • Guest operation modifications
    • Guest operation program execution
    • Guest operation queries
  • User credentials for the VM:
    • On Windows, you must have administrator privileges.
    • On Linux, you can use root or non-root credentials. For more information, see Guest discovery on Linux.

To collect data using VMware tools, follow these steps:

  1. Sign in to your Linux VM that's hosting the mcdc CLI.
  2. Change to the directory where you downloaded the mcdc CLI.
  3. Ensure that the VM is powered on.

  4. Run the guest discovery:

    Linux

    ./mcdc discover vsphere guest --url https://VSPHERE_URL -u VCENTER_USER --vm-user VM_USER VM_ID

    Windows

    mcdc.exe discover vsphere guest --url https://VSPHERE_URL -u VCENTER_USER --vm-user VM_USER VM_ID

    Replace the following:

    • VCENTER_USER: the vCenter server user
    • VM_USER: the VM user
    • VM_ID: the name of the VM or MOREF

  5. When prompted, enter the password for the VCENTER_USER and the VM_USER.

To collect data from multiple vSphere VMs in parallel using VMware tools, follow these steps:

  1. Sign in to your Linux VM that's hosting the mcdc CLI.
  2. Change to the directory where you downloaded the mcdc CLI.
  3. Ensure that all VMs are powered on.

  4. Run the guest discovery:

    Linux

    ./mcdc discover vsphere guest all --url https://VSPHERE_URL -u VCENTER_USER --vm-user VM_USER --timeout TIMEOUT_IN_SECONDS

    Windows

    mcdc.exe discover vsphere guest all --url https://VSPHERE_URL -u VCENTER_USER --vm-user VM_USER --timeout TIMEOUT_IN_SECONDS

    Replace TIMEOUT_IN_SECONDS with the timeout in seconds.

    Optionally, limit the discovery to only Windows or Linux VMs using the --os-family flag, or change the level of parallelism using the --max-parallelism flag.

  5. When prompted, enter the password for the VCENTER_USER and VM_USER.

  6. You can also scope the discovery to specific VMs using the --path flag, as described for VMware in Run an inventory discovery.

You can export and assess this collected data online in Migration Center, or run an offline assessment.

Guest discovery on Linux

If you run guest discovery with root access (for example, by using sudo), mcdc CLI collects more data from your machine than if you run it using non-root user credentials.

The following table compares the data collected by the guest discovery script based on privilege level.

Click to see what data is collected

Category Data Non-root access Root access
Hardware Product serial number Skipped:
requires root access.		 Collected:
from /sys/class/dmi/id/product_serial.
Networking Process-to-port mapping Partial:
connection information is collected, but PID/program names for other users' processes are not collected.		 Full:
all listening ports and connections are mapped to their respective PIDs and program names.
Middleware JBoss / Tomcat internals Limited:
only environment, descriptors, and limits for the current user's processes are accessible.		 Full:
reads process data (environ, fd, limits) for all middleware instances from /proc/[PID].
Storage Block devices and mounts Full:
standard tools such as lsblk and df that are accessible to users.		 Full:
block device details and system mounts.
Configuration Restricted system files Partial:
doesn't collect information from files such as /etc/exports and some Apache configurations that might be unreadable depending on permissions.		 Full:
root bypasses all file permission restrictions to gather the required configuration files.
Security SELinux status Restricted:
detailed configuration details is not collected.		 Full:
complete output is collected from the sestatus tool.
Inventory Installed packages Full:
standard package managers (dpkg, rpm) are accessible to all users.		 Full:
a complete list of all installed system packages are collected.

Collect data remotely over SSH

If the machine that's hosting the mcdc CLI has SSH access to the target Linux machine (Windows machines are not supported), then the mcdc CLI can connect to the target machine over SSH to collect data.

When using SSH, the mcdc CLI does the following:

  1. Uploads the collection script to the machine.

  2. Runs the script on the machine with the machine user credentials passed to the mcdc CLI.

  3. Downloads and imports the results.

Supported SSH modes

If you're using the mcdc CLI on a Linux machine, you can use two modes to run SSH:

  • Default: uses the ssh binary and configurations on the mcdc CLI machine. Default mode can use the local SSH configuration files by default, such as ~/.ssh/config and ~/.ssh/known_hosts, of the workstation that's hosting it.

    Enter the password when prompted, or use sshpass to pass the password or private key file passphrase on the command line. For example:

    sshpass -p password mcdc discover ssh IP_ADDRESS

    Replace IP_ADDRESS with the IP address of the machine.

  • Embedded: uses the built-in SSH library. This mode lets you use the embedded SSH client if default mode malfunctions in your environment. However, it doesn't use the local SSH configuration files by default. You can use the -i flag to specify an SSH private key file.

If you're using the mcdc CLI on a Windows machine, only embedded mode is supported.

Run the collection

To collect data over SSH, follow these steps:

  1. Sign in to the Linux machine that's hosting the mcdc CLI.
  2. Change to the directory where you downloaded the mcdc CLI.

  3. Collect data.

    Linux