vDocumentation

vDocumentation provides a community-created set of PowerCLI scripts that produce infrastructure documentation of vSphere environments in CSV or Excel file format. It was presented for general public use in VMworld 2017, session SER2077BU. You can watch the video here

https://www.youtube.com/watch?v=-KK0ih8tuTo

Original slides are here as well as the mindmap we used to create this talk. We are passionate about this subject so please use the slides or let us know what you would like to add to the MindMap, and we can continue improving this presentation.

If you already have installed vDocumentation, here's some quick instructions to determine your version and to upgrade if needed

Get-Module vDocumentation -ListAvailable | Format-List
Find-Module vDocumentation

If the available version in the Find-Module command is newer, use this command to uninstall the installed version (and repeat if you have several) and then install again

Uninstall-Module vDocumentation
Install-Module vDocumentation -Scope CurrentUser

If you have not installed vDocumentation or used PowerCLI much, here's the installation instructions

First time usage on a brand new machine with PowerShell 5.x (or newer) and an open internet connection

Paste in a PowerShell window that has been Run as Administrator and answer Y

Set-ExecutionPolicy RemoteSigned

You can now close the PowerShell window that ran as Administrator

In a new, normal PowerShell console, paste the below commands answering Y (this only affects your user, and it may take a while)

Install-Module -Name VMware.PowerCLI -Scope CurrentUser
Install-Module ImportExcel -scope CurrentUser
Install-Module vDocumentation -Scope CurrentUser

vDocumentation is now installed! You can verify with

Get-Module vDocumentation -ListAvailable | Format-List

The vDocumentation module gives you eight new PowerCLI Commands you can use to create documentation of a vSphere environment

Before you can use them, connect to your vCenter(s) using PowerCLI. Although if you have invalid certs, you will need this command first:

Set-PowerCLIConfiguration -InvalidCertificateAction Ignore -Confirm:$false

Connect-VIServer [IP_or_FQDN_of_vCenter] # Connect to one, or repeat for many vCenters

When prompted for credentials use a vCenter Administrator-level account. Once connected you can execute these commands:

|Command|Description| |----------------|---| |Get-ESXInventory|Document host hardware inventory and host configuration| |Get-ESXIODevice|Document information from HBAs, NICs and other PCIe devices including PCI IDs, MACs, firmware & drivers| |Get-ESXNetworking|Document networking configuration information such as NICs, vSwitches, VMKernel details| |Get-ESXStorage|Document storage configurations such as iSCSI details, FibreChannel, Datastores & Multipathing| |Get-ESXPatching|Document installed and pending patches, including related time and KB information| |Get-vSANInfo|Document basic vSAN Cluster information| |Get-ESXSpeculativeExecution|Document ESXi host mitigation status for Spectre and Meltdown| |Get-VMSpeculativeExecution|Document VM mitigation status for Spectre and Meltdown|

Each script will output the corresponding data to terminal, and optionally create a file (XLSX, CSV) with the command name and a timestamp. You can use command switches to customize CSV or Excel output, file path (default is powershell working directory), and the command scope (report on all connected vCenters or just cluster or host). Please check the section after the changelog for more details

Changelog

v2.4.7

Fixed default parameterSet to gather all hosts information if a -VMhost, -Cluster, or -Datacenter is not specified
Fixed Get-ESXIODevice, so that all Invoke-WebRequest cmdlet now uses -UseBasicParsing

v2.4.6

• For us to gather the ESXi version we used $vmhost.ApiVersion before, now its updated to be $vmhost.version and the update level. With this we have removed update and patch level columns in any of the cmdlet reports because the patch level did not reflect the patch level tracked under: https://kb.vmware.com/s/article/2143832
• Flagged by Michael White, we got a usability change that wasn't tracked in our changelogs: All cmdlets use parameterset now and there is not a default one, so now you really need to specify -VMhost or -Cluster or -Datacenter. Justin Sider has proposed setting a default value, and Edgar is now tinkering to bring it back to the old behavior.

v2.4.5.2

• Bug workaround to fix issue in Windows Server 2012 when retrieving HCL URLs

This fails:
webElement = $webRequest.ParsedHtml.body.getElementsByTagName("script") | Where-Object { $_.type -eq "text/javascript"}

changed to:
$webElement = $webRequest.AllElements | Where-Object { $_.tagName -eq "script"}

slower but it works!

v2.4.5

• Updated Get-ESXSpeculativeExecution to report on L1TF (VMSA-2018-0020)

• Fixed bug reported by Jeffery Barrow in Get-vSANInfo Cmdlet

• Improvement added, suggested by @pdpelsem to include VMware HCL URLs as part of the Get-ESXIODevice Cmdlet. We expanded on his idea by adding a 2nd tab output that will dump the pertinent HCL information gathered against the VMware HCL IO online site (if you have internet connection), see his code and issue report here https://github.com/arielsanchezmora/vDocumentation/issues/44

• All Cmdlet now use -VMhost instead of -ESXi, these were changed to parameter set and will help with future code improvements

• Minor code optimizations and fixes

v2.4.1 Meaty release updating three of the new cmdlets - lots of work by Edgar especially regarding Spectre/Meltdown checks. vDocumentation has has over 1000 downloads in the PowerShell Gallery!

Get-vSANInfo gets updates! Thanks Graham Barker (twitter <a href="https://twitter.com/VirtualG_UK" target="_blank"> @VirtualG_UK</a> website <a href="https://virtualg.uk/" target="_blank"> virtualg.uk</a>)! Code cleaning: • General code cleanup (remove old comments etc) Additions: • Code execution time improvement • Validate that vCenter Server is running at least version 6.5.0 before execution Bug Fixes: • Fixed bug with calculating vSAN cluster sizes • Fixed typo in Excel tab • Tested against larger cluster

Edgar Sanchez (twitter <a href="https://twitter.com/edmsanchez13/" target="_blank"> @edmsanchez13</a>) has Updated Get-ESXSpeculativeExecution and Get-VMSpeculativeExecution for new Intel MCU checks. To really follow and understand all the complexities, please see his blog post <a href="https://virtualcornerstone.com/2018/03/19/verify-new-spectre-mitigation-patches-using-powercli-and-vdocumentation/" target="_blank"> virtualcornerstone.com</a>.

Fixed Issue #31 reported by OlivierFaucon, thank you! https://github.com/arielsanchezmora/vDocumentation/issues/31

v2.4.0 Rapid release by project lead Edgar Sanchez (twitter <a href="https://twitter.com/edmsanchez13/" target="_blank"> @edmsanchez13</a>) to follow up with latest VMware security releases. The changes are explained in more detail on his blog <a href="https://virtualcornerstone.com/2018/01/11/validating-compliance-of-vmsa-2018-0004-spectre-on-esxi-and-vm/" target="_blank"> virtualcornerstone.com</a>.

Additions:

• Get-ESXSpeculativeExecution cmdlet has been updated to validate the second wave of Spectre patches (VMSA-2018-0004), including a new check for newly exposed CPU instructions, and the BIOS check has been updated to also look for CPU microcode updates provided by VMware in https://kb.vmware.com/s/article/52085.

• Get-ESXSpeculativeExecution will now also report on VM Hypervisor-Assisted Guest Mitigations if -ReportOnVMs is manually specified (this is easier for generating large reports). Due to this report only being valid after Guest OS mitigations and VMHardware has been updated, we felt adding it as an extra option was more appropriate instead of a standalone function.

• In a first for vDocumentation, we've added a cmdlet which does not generate a report by itself, but is useful for checking VM compliance interactively in Powershell. You can now pipe a VM Object (not the VM name) to Get-VMSpeculativeExecution to get report on VM compl