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:

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 @VirtualG_UK website virtualg.uk)! 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 @edmsanchez13) 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 virtualcornerstone.com.

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 @edmsanchez13) to follow up with latest VMware security releases. The changes are explained in more detail on his blog virtualcornerstone.com.

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 compliance. Usage examples:
  Get-VM "testvm" | Get-VMSpeculativeExecution
Get-VMHost "hostname.fqdn" | Get-VM | Get-VMSpeculativeExecution | Export-Excel "HostVMSpectreReport.xlsx" -WorkSheetname "VMresults"

While this cmdlet can be piped into a report like in the second example above, please remember you can use the -ReportOnVMs switch for Get-ESXSpeculativeExecution - it's easier and the filename with timestamp will be created automatically for you.

Bug Fixes: none

v2.3.0 Very meaty update, with a new cmdlet aimed at verifying the first wave of vSphere mitigations against Meltdown and Spectre (VMSA-2018-0002 and manufacturer-issued BIOS updates) developed by project lead Edgar Sanchez (twitter @edmsanchez13). A much better overview of the new function can be found on his blog virtualcornerstone.com.

Additions:

• Added Get-ESXSpeculativeExecution Cmdlet to check compliane for VMSA-2018-0002 Security Advisory and BIOS version. He is already working on additional checks for v2.3.1

  Bug Fixes:

• Code fix in Get-ESXPatching - now able to get reference URLss for description fields containing "https" (example: ESXi650-201712103-SG is https://kb.vmware.com/kb/000051196)

• Get-ESXInventory - Added more details for ESXi Install source

  * Device Model
  * Boot Device
  * Runtime Name
  * Device Path

v2.2.0 Another meaty update, with a new vSAN cmdlet donated by Graham Barker (twitter @VirtualG_UK website virtualg.uk)! This brings the total number of vDocumentation cmdlets to six from our initial launch of 4!

Additions:

• Added new Cmdlet: Get-vSANInfo, NOTE! It depends on Get-VsanClusterConfiguration which only works on vSphere 6.5! Documentation update and examples coming soon!

• Added RAC MAC to Get-ESXInventory

  Bug Fixes:

• Minor code fixes in Get-ESXInventory, Get-ESXIODevice, and Get-ESXPatching

v2.1.0 Meaty update, our first new cmdlet since the project's debut!

Additions:

• Added new Cmdlet: Get-ESXPatching, documentation update and examples coming soon!

• Added the following to Get-ESXInventory, Configuration tab: SSH and ESXi Shell Service details requested by akozlow in Issue #19, and Boot Time

  Bug Fixes:

• Fixed reported issue #16 by DaveBF 'VMHostNeworkInfo type is deprecated' in Get-ESXNetworking Cmdlet
• Fixed issue for Uptime in Get-ESXInventory where it was not being calculated correctly

v2.0.0 Major update, on the backend, mostly safe for actual users

Code cleaning:
Each script module exists now in its own .ps1 file which will allow easier editing by the community
Scripts code optimization and formatting updated
@jpsider championed the removal of the CLS command that would clear screen before starting screen output, and contributed the code, which was included in this release.

Removed:
Get-ESXInventory function (and thus, a report column) removed: Deprecated script Cmdlet - Software/Patch Name(s) from host configuration has been deprecated. What Patches gets pushed can be manually verified using the Build ID

Additions:
@jpsider championed the addition of a -passthru option and contributed the code, which was included in this release.
Get-ESXInventory - Host Configuration script now has the following:

• Gather ESXi Installation Type and Boot source
• Gather ESXi Image Profile
• Gather ESXi Software Acceptance Level
• Gather ESXi Uptime (thanks to the person who asked in #SER2077BU, send us your name to give you credit!)

• Gather ESXi Install Date

  Get-ESXIODevice - NIC and HBA script now has the following:

• Updated string match to check for HPSA firmware, as it changed between 5.5, and 6.0 and possibly between firmware versions.

  Bug Fixes:
  Fixed Get-ESXNetworking script Cmdlet when querying UCS environment, or 3rd party Distributed switches. While the information retrieved is not the same (due to the powershell command, not because of vDocumentation) the script will no longer fail, and will produce what it can.

v1.0.4 new functionality added:

Updated export-excel so that it does no number conversion (IP addresses are now text) on any of the columns and it auto sizes them. Thanks to @magneet_nl for helping us discover this bug!

v1.0.3 new functionality added:

Get-ESXInventory: Added RAC Firmware version, BIOS release date.
Get-ESXIODevice: Added support to get HP Smart Array Firmware from PowerCLI

1.0.2 Formatting & Manifest changes

1.0.1 Changes to support displaying datastore multipathing

1.0.0 First release to PowerShell Gallery with 4 commands: Get-ESXInventory, Get-ESXIODevice, Get-ESXNetworking & Get-ESXStorage

Command switch options

Running a command without switches will

• report on all virtual datacenters in all connected vCenters
• output to PowerShell terminal only
• include all data tabs for each command

To change this behaviour use these switches:

You can see the full syntax with the Get-Help command

get-help Get-ESXInventory -ShowWindow

Example Outputs

Get-ESXInventory -Hardware

Get-ESXInventory -Configuration

Get-ESXIODevice (only has one tab)

Get-ESXNetworking -VirtualSwitches (standard switch)

Get-ESXNetworking -VirtualSwitches (distributed switch)

Get-ESXNetworking -VMKernelAdapter

Get-ESXNetworking -PhysicalAdapters

Get-ESXStorage -StorageAdapters

Get-ESXStorage -Datastores

iSCSI output thanks to @michael_rudloff, see his

CSV outputs thanks to @magneet_nl, see his

Document your vSphere environment? Yes you can! Blog article with Excel outputs thanks to @mwVme

Uninstalling the vDocumentation script

Uninstall-Module vDocumentation

Upgrading from a previous version

There is a known limitation in just upgrading through the PowerShell Gallery: using the Update-Module command installs a new version but does not remove the old version. While PowerShell/PowerCLI will use the latest module, if you wish to only have the latest listed in your computer, uninstall all existing vDocumentation modules before installing the latest by using Uninstall-Module as many times as needed, before using Install-Module as with a new installation.

However, in an effort to keep it simple, you can just use the following commands (and again, it does seem it always uses the latest version). If the prompt returns without doing anything, you are already running the latest.

Update-Module VMware.PowerCLI
Update-Module ImportExcel
Update-Module vDocumentation

FAQ

What if I don't have internet?

• A great guide to follow is https://blogs.vmware.com/PowerCLI/2017/04/powercli-install-process-powershell-gallery.html

How do I know which PowerShell version I am running?

To upgrade follow links such as https://docs.microsoft.com/en-us/powershell/scripting/setup/windows-powershell-system-requirements?view=powershell-5.1

What if I can't run PowerShell 5.x?

• If ESXi and vCenter are hardened to only talk on TLS v1.2, you need .Net 4.5 or above for PowerShell to support this.

What is the ImportExcel module?

• Read about ImportExcel

Does this run on PowerCLI core?

• We'd love to know! We haven't tested it yet; expect an update soon.

Why do I get a warning about deprecated features when running the script?

• This is native from PowerCLI as they plan future changes. vDocumentation does not use any feature that is known to be in deprecation plans. You can disable the warnings with Set-PowerCLIConfiguration -DisplayDeprecationWarnings $false -Scope User

I get certificate warnings

• You can disable self-signed certificate warnings with the following command, or install proper certs ;)

Set-PowerCLIConfiguration -InvalidCertificateAction Ignore

I get this error "Get-EsxCli : A parameter cannot be found that matches parameter name 'V2'" why?

• This probably means you are running a version of PowerCLI that is older than 6.3. We encourage uninstalling all versions and then using the latest version - that should take care of this error, which comes from a feature that was added in PowerCLI 6.3

vDocumentation backstory

Hi! I'm Ariel Sanchez (https://twitter.com/arielsanchezmor) and this is the result of a dream and the power of the vCommunity. I started a documentation template effort, which can be found here. There is a lot of work pending to be able to call the effort complete, but one very important component that my friend Edgar Sanchez ( https://twitter.com/edmsanchez13 ) has advanced dramatically is the PowerCLI scripting. This repository stores them, and publishes them to the world so they can start being used. We open-sourced and placed in GitHub so they can be further improved by the vCommunity!

The main motivation for this project was the sad state of vSphere infrastructure documentation accessible to many vSphere administrators. It is demoralizing to start a new job, ask for documentation, and find there is none. The situation is bad enough when the documentation is outdated, but even worse when it's plain wrong. It's also challenging to be tasked with creating documentation, realizing that creating it manually would take a long time, and that collecting and customizing all the scripts will take a long time as well.

Thus, our goal is to be able to easily produce documentation "direct from vCenter" that is relevant to what your manager or another VMware administrator wants to see. The best part is, you only need to run the scripts and they create the needed CSV or Excel file for you. This means you can update your documentation at a moment's notice, and even better, review it to identify things in your environment that may not have been easily visible before.

The license on these scripts is a MIT style license - use as you will. Like all the PowerCLI greats have told us before, steal and modify whatever you find useful. We definitely have stolen from all over the internet to create these (and have tried to credit those who we stole from). Special shout-outs to Luc Dekens, William Lam, Alan Renouf, Kyle Ruddy - and many more in the vCommunity.

Our goal is that this project is useful to others and it will be accepted in the official VMware PowerCLI examples. Please, let us know if you found this useful, had trouble running it, or anything that you want to see changed. We are new to GitHub but actively learning - use GitHub or reach out to us on twitter or in the VMware Code Slack (https://code.vmware.com/web/code/join)

To a future where walking into a new place and asking for documentation is greeted with "Yup, we use vDocumentation" and the interested party replies "Perfect!" :)

Syntax

Get-Help Get-ESXInventory

NAME Get-ESXInventory

SYNOPSIS Get basic ESXi host information

SYNTAX Get-ESXInventory [[-esxi]