Using the Linux discovery tool

Migrate for Anthos provides a self-service tool that you run on a Linux VM workload to determine the workload's fit for migration to a container.

The tool outputs a report describing the analysis results for the VM that describes any issues that must be resolved before migration and an overall fit assessment of either:

Excellent fit.
Good fit with some manual work.
Needs minor work before migrating.
Needs moderate work before migrating.
Needs major work before migrating.
No fit.

How the tool works

The Linux discovery tool operates in two distinct phases:

Collect phase - A bash script named m4a-fit-collect.sh collects information about the Linux VM to be migrated and writes the collected data to a tar file. A copy of the data remains on the VM filesystem for later usage during migration.

Note: The script examines both /etc/fstab and /proc/self/mounts. If the script detects any clear-text passwords or other privacy information in /etc/fstab or /proc/self/mounts, the information is excluded from the output.
Analysis phase - The m4a-fit-analysis tool parses the output of the collect phase, applies a set of rules, and creates a fit assessment along with a detailed report describing the tool's findings. You can view the report as an HTML file or as a JSON file.

You can run the collect tool and analysis tool on the same VM. However, if you have multiple VMs, you can instead run the collect tool on each VM separately, then upload the tar file from each VM to a single machine for analysis. The m4a-fit-analysis tool can process multiple tar files at once to output a fit assessment and analysis for each VM.

HTML output

The following image shows the HTML output of the tool for the evaluation of a VM named "my-vm":

Where:

The table contains one row for each VM analyzed, including a link to details about the VM.
The Data collection date, Identified OS, M4A fit score, and Workload type columns contain summary information about the VM and the analysis results.
The Additional info column contains a link to details about each VM, including information such as listening ports, mount points, NFS mount points, and other information.
Each rule column shows the results from applying a rule to the VM. A value of:
- Not Detected means that rule detected no migration issue.
- Detected means the rule detected a migration issue for the VM. Click Detected to view details about the rule output.

Prerequisites

The Linux discovery tool has the following prerequisites:

The target VM being evaluated must be running to ensure that applications, processes, and open ports are discoverable.
The machine used to run the analysis tool, m4a-fit-analysis, must run Linux kernel version later than 2.6.23.
You must run the collect script as sudo.

Installing and running the tool

You must download the collection script and the analysis tool. You can either:

Download both tools to a single VM.
If you have multiple VMs, download the collection script to each workload VM, then upload the collected data to a central machine for analysis by the analysis tool.

To evaluate a VM:

Log in to your VM.
Create a directory for the collection script and analysis tool:
```
mkdir m4a
cd m4a
```

Download the collection script to the VM and make it executable:

wget https://anthos-migrate-release.storage.googleapis.com/v1.7.0/linux/amd64/m4a-fit-collect.sh
chmod +x m4a-fit-collect.sh

Download the analysis tool to the VM and make it executable:

wget https://anthos-migrate-release.storage.googleapis.com/v1.7.0/linux/amd64/m4a-fit-analysis
chmod +x m4a-fit-analysis

Run the collect script on the VM:
```
sudo ./m4a-fit-collect.sh
```
The script outputs a tar file named m4a-collect-machinename-timestamp.tar to the current directory and to /var/m4a/m4a-collect-timestamp.tar.

The timestamp is in the format YYYY-MM-DD-hh-mm. See Collect script operation for a description of the tar file format.

Note: If you installed the analysis tool on a central machine, upload the tar file to that machine for processing.
Run the analysis tool on the tar file:
```
./m4a-fit-analysis m4a-collect-machinename-timestamp.tar
```
The tool outputs two files to the current directory:
- An HTML file named analysis-report-timestamp.html. The timestamp is in the format YYYY-MM-DD-hh-mm. View this file in a browser to examine the report.
- A JSON file named analysis-report-timestamp.json containing a JSON format of the output. You can use the file as input to data visualization tools.
The output files contain information about the analysis, including the fit assessment. See Report file format for more information.

To run the analysis tool on multiple tar files, you can use the command:
```
$ ./m4a-fit-analysis tarFile1 tarFile2 tarFile3 ...
```
The tool outputs a single row to the output files for each input tar file. Within the report, you can identify each VM by its hostname, meaning the value returned by running the hostname command on the VM.

Use the --verbosity option to control the output of the tool. Options include: panic, fatal, error(default), warning, info, debug, and trace.
Open analysis-report-timestamp.html in a browser to view the report. See Analysis tool operation for a description of the file format.

Collect script operation

The collect script runs a series of Linux commands to gather information about the source VM and also collects information from several files on the VM.

The following sections describe the operation of the script. You can also examine the script in a text editor to see more detailed information.

Script commands

The script runs the following Linux commands:

Command	Description
`netstat -tlnp`	List all active listening ports
`ps -o pid,user,%mem,comm,args -e`	List of all running user processes
`dpkg -l`	List installed packages (debian based)
`rpm -qa`	List of installed packages (rpm based)
`sestatus`	Get SELinux status
`lsmod`	Get loaded kernel modules
`systemctl`	List running services (SystemD baseD)
`service --status-all`	List running services (Init.d /Upstart based)
`lsof /dev /`	List open handles to files and hardware devices
`docker ps`	List running Docker containers
`ip addr`	List IP addresses assigned to NICs
`ifconfig`	Show NIC configs and assigned IPs
`blkid`	List block device attributes
`lsblk --json -p --output NAME,PARTFLAGS,PARTTYPE,UUID,LABEL,FSTYPE"`	List block devices

Files collected

The script copies the following files to the generated tar file:

Path	Description
`/etc/fstab`	List of mounts to be mounted at startup
`/etc/hosts` `/etc/resolv.conf` `/etc/hostname` `/etc/HOSTNAME` `/proc/sys/kernel/hostname`	Aliases for hosts and DNS data
`/etc/issue` `/etc/*-release`	The name of the Linux distribution
`/etc/network/interfaces` `/etc/dhcp/dhclient-up-hooks` `/etc/NetworkManager/conf.d/` `/etc/systemd/resolved.conf` `/etc/sysconfig/network-scripts/` `/etc/sysconfig/network/*`	The configured interfaces
`/proc/cpuinfo`	CPU information
`/proc/meminfo`	The current memory usage/total on the VM
`/proc/self/mounts`	The currently mounted devices
`/etc/exports`	List of NFS exports
`/opt/IBM/WebSphere/AppServer/properties/version/installed.xml`	Websphere version (when installed at default)
`/opt/IBM/WebSphere/AppServer/properties/version/WAS.product`	Websphere info (when installed at default)

Directories examined

The script searches the following directories, to a depth of two, to locate the directories of installed utilities and software:

/opt/
/usr/share/
/etc/
/usr/sbin/
/usr/local/bin/

Collect tar file format

The m4a-fit-collect.sh script outputs a tar file named m4a-collect-machinename-timestamp.tar to the current directory and to /var/m4a/m4a-collect-timestamp.tar.

While not required, you can optionally expand the tar file by using the command:

tar xvf m4a-collect-machinename-timestamp.tar

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 version number of the script

Analyze tool operation

The analyze tool examines the contents of the tar file from a VM, applies a set of rules, and outputs the following report files containing the fit assessment and analysis results:

An HTML file named analysis-report-timestamp.html to the current directory. The timestamp is in the format YYYY-MM-DD-hh-mm.
A JSON file named analysis-report-timestamp.json containing a JSON format of the output. You can use the JSON file as input to data visualization tools.

Calculating the fit assessment

A rule violation detected by the tool affects the final fit assessment, where each rule has its own predefined severity. For example, the tool detects the SELinux is enabled on the VM, corresponding to rule SEL01: SELinux enforced. That rule has a severity of "Needs moderate work before migrating" so the final fit assessment of the tool is "Needs moderate work before migrating".

If the tool detects multiple rule violations, then only the rule with the highest severity is applied to the final fit assessment. For example, two rule violations are detected:

An incompatible file system is detected, rule IFS01: incompatible filesystem, with a severity of "No fit".
SELinux enabled is detected with a severity of "Needs moderate work before migrating".

The tool only returns the fit assessment associated with the most severe of the two rules. Therefore, it returns "No fit".

HTML report file format

The HTML file contains a row describing each VM analyzed, and a set of columns that show the results from applying each rule to the VMs. Each rule column displays either:

Not Detected means that rule detected no migration issue.
Detected means the rule detected a migration issue for the VM. Click Detected to view details about the rule output.

Report columns

The HTML file contains the following columns:

Column name	Description	Severity	Notes
`VM name`	The name of the VM.
`Data collection date`	The timestamp of the analysis, in the form: `YYYY-MM-DD-hh-mm`
`Identified OS`	The operating system which is always `Linux`.
`M4A fit assessment`	The fit assessment. See for information on interpreting this assessment.
`Workload type`	If detected, shows IBM WebSphere. Note: If the workload type is IBM WebSphere version 8.5 or 9, the fit assessment is always "Excellent fit". This is because a WebShphere VM is expected to work well with the WebSphere migration flow preview release.
`Additional info`	Summary of information about the VM, including: Listening ports discovered on the VM. Detected disk mounts on the VM. NFS mount points on the VM.
`NET01: Unsupported network mount`	If `/etc/fstab` or `/proc/self/mounts` has network mounts, you need to manually add the CSI volumes to the migration plan.	Good fit	See Mounting External Volumes for more on how to attach NFS/CIFS volumes to deployment YAML.
`IFS01: Incompatible filesystem`	Incompatible file-system.	No fit	You cannot migrate workloads with an incompatible file system.
`SEL01: SELinux enforced`	SELinux does not work well in nested containers so the recommendation is to disable it before migrating.	Needs moderate work	Disable SELinux or manually apply an `apparmor` profile before migrating.
`FSE*: NFS share exported`	Detected an NFS export file and the NFS server kernel module is loaded. Two rules are applied, where each returns a different severity: FSE01: NFS server detected: Needs moderate effort FSE02: NFS server detected and Workload type is web server: Needs minor effort	See description	Migrate NFS servers to Cloud Filestore.
`LIP*: Found listener on non-0.0.0.0 IP address`	Binding to a specific network interface detected. If there are ports being listened to on a specific NIC (and not 0.0.0.0, , or loopback) it usually means there is a multi-NIC setup. Three rules are applied, where each returns a different severity: LIP01: One IP detected: Good fit LIP02: Two or more IPs detected: Needs minor work LIP03*: Two or more IPs detected listening on the same port: Needs moderate work	See description	Update VM to listen on any one NIC because Migrate for Anthos only supports one NIC.
`DBC01: Running DB inside container`	Check for running database applications that are not a good fit for migration: Mysqld Postgres Mongodb Redis-server Cassandra Elasticsearch	Needs minor work	Consider migrating to Cloud SQL.
`DR01: Docker running on VM`	Nesting Docker inside containers is not supported.	If `dockerd` is running: Good fit	Consider using Migrate for Compute Engine or running the containers directly on GKE/Anthos.
`SHD01: Usage of static hosts`	Static hosts definitions detected in `/etc/hosts`.	Good fit	See Adding entries to Pod /etc/hosts with HostAliases for information on modifying your static hosts.
`BD01: Open block device`	Open block device detected by `lsof`.	No fit	Not compatible with Migrate for Anthos.

Changes to the tool for Migrate for Anthos 1.7

For the Migrate for Anthos 1.7 release, we added new features and changed existing features of the tool. The following table describes these changes:

Change	Description
Removed the fit score.	In the previous release, the fit score was in the range of 0 (no fit) to 10 (great fit). The score has been replaced by an assessment value as shown above.
The weight of all rules has been removed.	The weight of all rules have been removed and replaced with an assessment result.
Replaced the CSV file report format with an HTML and a JSON file.	Use the HTML file to view the report in a browser, and use the JSON file as input to a data visualization tool. See HTML report file format for more.
Location of the tar file created by `m4a-fit-collect.sh`	As in previous release, the script writes the tar file to the current directory, but now it also writes it to `/var/m4a/m4a-collect-timestamp.tar`.
Version file added to the tar file created by `m4a-fit-collect.sh`	The file contains the version of the script.
Added new column for the detected Workload type	If detected, shows IBM WebSphere. Note: If the workload is IBM WebSphere version 8.5 or 9, the fit assessment is always "Excellent fit". This is because a WebShphere VM is expected to work well with the WebSphere migration flow preview release.
Added new summary fields for each VM in the report.	These fields include the listening ports, mount points, NFS mount points, and other information.

What's next

Setting up Migrate for Anthos