This document describes the steps to run the different guest discovery methods
that the mcdc
CLI provides.
Overview
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 VMs running on Azure or machines running on-premises, as well as for a full assessment of VMs running on VMware and AWS, 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 thediscover vsphere
command. - For Linux machines accessible by the
mcdc
CLI, you can perform a remote discovery using SSH with thediscover ssh
command. - For Windows machines accessible by the
mcdc
CLI, you can perform a remote discovery using Windows Management Instrumentation (WMI) with thediscover 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 hosting themcdc
CLI.
The guest collection script runs a series of commands to gather information about the source machine and also collects information from several files on the machine.
Before you begin
- Review the requirements for downloading and running the
mcdc
CLI. - Review the requirements for downloading and running the guest collection scripts.
- 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, root access is not required, but root access allows
mcdc
CLI to collect the data required for a complete assessment.
To collect data using VMware tools, follow these steps:
- Log in to your Linux VM hosting the
mcdc
CLI. - Change to the directory where you downloaded the
mcdc
CLI. - Ensure that the VM is powered on.
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
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:
- Log in to your Linux VM hosting the
mcdc
CLI. - Change to the directory where you downloaded the
mcdc
CLI. - Ensure that all VMs are powered on.
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.When prompted, enter the password for the VCENTER_USER and VM_USER.
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.
Collect data remotely over SSH
If the machine 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:
- Uploads the collection script to the machine.
Runs the script on the machine with the machine user credentials passed to the
mcdc
CLI.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 themcdc
CLI machine. Default mode can use the local SSH configuration files by default, such as~/.ssh/config
and~/.ssh/known_hosts
, of the workstation 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:
- Log in to the Linux machine hosting the
mcdc
CLI. - Change to the directory where you downloaded the
mcdc
CLI. Collect data:
Linux
./mcdc discover ssh IP_HOSTNAME
Windows
mcdc.exe discover ssh IP_HOSTNAME
Replace IP_HOSTNAME with the IP hostname of the machine.
The SSH private key file of the user invoking the
mcdc
CLI is used for SSH authentication.When prompted, enter the username of an account on the Linux machine. The collection script runs using these credentials. If the SSH private key of the user invoking the
mcdc
CLI fails to authenticate to the machine with the username, you're also prompted for a password.
Additional scenarios when using SSH
See the following scenarios where you might need to modify the command:
To specify the machine user with default mode, use the
-u
flag:Linux
./mcdc discover ssh -u USER IP_HOSTNAME
Windows
mcdc.exe discover ssh -u USER IP_HOSTNAME
Replace USER with the machine user.
When prompted, enter the password for the user.
To specify verbose mode, use the
-v
flag:Linux
./mcdc discover ssh -u USER -v IP_HOSTNAME
Windows
mcdc.exe discover ssh -u USER -v IP_HOSTNAME
To specify the SSH private key file, use the
-i
flag. For example, to specify.ssh/my_private_key
:Linux
./mcdc discover ssh -i ~/.ssh/my_private_key -u USER IP_HOSTNAME
Windows
mcdc.exe discover ssh -i ~/.ssh/my_private_key -u USER IP_HOSTNAME
To specify the password on the command line, use embedded mode:
Linux
./mcdc discover ssh --ssh-client embedded -u USER --passphrase PASSWORD IP_HOSTNAME
Windows
mcdc.exe discover ssh --ssh-client embedded -u USER --passphrase PASSWORD IP_HOSTNAME
Because the embedded form of the command doesn't use the local SSH configuration files by default, ensure that the user you specify in the command is able to access the machine over SSH and has privileges on the machine to execute the collection script.
To specify the SSH private key file with embedded mode, use the
-i
flag:Linux
./mcdc discover ssh --ssh-client embedded -i ~/.ssh/id_rsa -u USER --password PASSWORD IP_HOSTNAME
Windows
mcdc.exe discover ssh --ssh-client embedded -i ~/.ssh/id_rsa -u USER --password PASSWORD IP_HOSTNAME
The
mcdc
CLI command lets you specify most SSH flags. It then passes these flags to thessh
command using the-a
or--ssh-args
flag. For example, to use a socks proxy:Linux
./mcdc discover ssh -u USER -a '-o' -a 'ProxyCommand=nc -X 5 -x 127.0.0.1:proxy port %h %p' IP_HOSTNAME
Windows
mcdc.exe discover ssh -u USER -a '-o' -a 'ProxyCommand=nc -X 5 -x 127.0.0.1:proxy port %h %p' IP_HOSTNAME
You can export and assess this collected data online in Migration Center, or run an offline assessment.
Collect data remotely over WMI
If you want to perform a guest discovery on a target Windows machine with WMI
support, you can use the mcdc discover wmi
command on the Windows machine
hosting the mcdc
CLI. WMI collection is supported
only on the Windows version of the mcdc
CLI.
When using WMI, the mcdc
CLI does the following:
- Uploads the collection script to the machine.
Runs the script on the machine with the machine user credentials passed to the
mcdc
CLI.Downloads and imports the results.
To collect data over WMI, follow these steps:
- Log in to the Windows machine hosting the
mcdc
CLI. - Change to the directory where you downloaded the
mcdc
CLI. Collect data:
mcdc.exe discover wmi IP_HOSTNAME
Replace IP_HOSTNAME with the IP hostname of the machine.
Enter your credentials when prompted.
Collect data on an individual Linux machines
To perform a guest collection locally on a Linux machine, you can run the
mcdc-linux-collect.sh
script.
Then, you can copy the tar file generated by the script into the machine that
hosts the mcdc
CLI, and import it with the
discover import
command.
You typically run the script by specifying the sudo
option.
Optionally, you can run the script using the privileges of the user running
the mcdc
CLI. However, the script might not be able to
collect all the required data.
- Log in to your machine.
- Change to the directory where you downloaded the guest collection script.
Run the collection script on the machine:
sudo ./mcdc-linux-collect.sh
The script outputs a tar file named
mcdc-collect-MACHINE_NAME-TIMESTAMP.tar
to the current directory. The timestamp is in the formatYYYY-MM-DD-hh-mm
.Click to see the guest collection tar file format
The tar file has the following format:
collect.log # Log output of the script files # Directory containing files with their full path from root. For example: |- etc/fstab |- etc/hostname |- etc/network/interfaces |- ... commands # Output of commands run by the script: |- dpkg |- netstat |- ps |- ... found_paths # Text file with the list of installation directories machinename # Text file with machine name ostype # Text file with operating system type (Linux) timestamp # Text file with collection timestamp version # Text file with the version of the script
Optionally, you can pass the argument
--output
and specify the path where you want to save the tar file.Copy the collected data from the target machine to the host machine.
Import the collected data on the host machine:
Linux
./mcdc discover import PATH_TO_TAR
Windows
mcdc.exe discover import PATH_TO_TAR
Replace PATH_TO_TAR with the path to the tar file.
You can export and assess this collected data online in Migration Center, or run an offline assessment.
Collect data on an individual Windows machine
To perform a guest collection locally on a Windows machine, you can run the
mcdc-windows-collect.ps1
script.
Then, you can copy the zip file generated by the script into the machine that
hosts the mcdc
CLI, and import it with the
discover import
command.
- Log in to your machine.
- Open PowerShell using the Run as Administrator option.
- Change to the directory where you downloaded the
mcdc
CLI. Run the collection script on the machine:
powershell -ExecutionPolicy ByPass -File .\mcdc-windows-collect.ps1
The script outputs a zip file named
mcdc-collect-MACHINE_NAME-TIMESTAMP.zip
to the current directory.Optionally, you can include an output path to specify a different location:
.\mcdc-windows-collect.ps1 PATH_FOR_OUTPUT.zip
Import the collected data on the host machine:
Linux
./mcdc discover import PATH_TO_TAR
Windows
mcdc.exe discover import PATH_TO_TAR
Replace PATH_TO_TAR with the path to the tar file.
You can export the collected data and assess it online in Migration Center, or run an offline assessment.
What's next
- Learn how to run an IP range scan.
- Learn how to export collected data to Migration Center.