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 #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! #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] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [-Hardware] [-Configuration] [[-folderPath] ] []

DESCRIPTION Will get inventory information for a vSphere Cluster, Datacenter or individual ESXi host The following is gathered: Hostname, Management IP, RAC IP, ESXi Version information, Hardware information and Host configuration

RELATED LINKS https://github.com/arielsanchezmora/vDocumentation

REMARKS To see the examples, type: "get-help Get-ESXInventory -examples". For more information, type: "get-help Get-ESXInventory -detailed". For technical information, type: "get-help Get-ESXInventory -full". For online help, type: "get-help Get-ESXInventory -online"

Get-Help Get-ESXIODevice

NAME Get-ESXIODevice

SYNOPSIS Get ESXi vmnic* and vmhba* VMKernel device information

SYNTAX Get-ESXIODevice [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [[-folderPath] ] []

DESCRIPTION Will get PCI/IO Device information including HCL IDs for the below VMkernel name(s): Network Controller - vmnic* Storage Controller - vmhba* Graphic Device - vmgfx* All this can be gathered for a vSphere Cluster, Datacenter or individual ESXi host

RELATED LINKS https://github.com/arielsanchezmora/vDocumentation

REMARKS To see the examples, type: "get-help Get-ESXIODevice -examples". For more information, type: "get-help Get-ESXIODevice -detailed". For technical information, type: "get-help Get-ESXIODevice -full". For online help, type: "get-help Get-ESXIODevice -online"

Get-Help Get-ESXNetworking

NAME Get-ESXNetworking

SYNOPSIS Get ESXi Networking Details.

SYNTAX Get-ESXNetworking [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [-VirtualSwitches] [-VMkernelAdapters] [-PhysicalAdapters] [[-folderPath] ] []

DESCRIPTION Will get Physical Adapters, Virtual Switches, and Port Groups All this can be gathered for a vSphere Cluster, Datacenter or individual ESXi host

RELATED LINKS https://github.com/arielsanchezmora/vDocumentation

REMARKS To see the examples, type: "get-help Get-ESXNetworking -examples". For more information, type: "get-help Get-ESXNetworking -detailed". For technical information, type: "get-help Get-ESXNetworking -full". For online help, type: "get-help Get-ESXNetworking -online"

Get-Help Get-ESXStorage

NAME Get-ESXStorage

SYNOPSIS Get ESXi Storage Details

SYNTAX Get-ESXStorage [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [-StorageAdapters] [-Datastores] [[-folderPath] ] []

DESCRIPTION Will get iSCSI Software and Fibre Channel Adapter (HBA) details including Datastores All this can be gathered for a vSphere Cluster, Datacenter or individual ESXi host

RELATED LINKS https://github.com/arielsanchezmora/vDocumentation

REMARKS To see the examples, type: "get-help Get-ESXStorage -examples". For more information, type: "get-help Get-ESXStorage -detailed". For technical information, type: "get-help Get-ESXStorage -full". For online help, type: "get-help Get-ESXStorage -online"

Get-Help Get-ESXPatching

NAME Get-ESXPatching

SYNOPSIS Get ESXi patch compliance

SYNTAX Get-ESXPatching [[-esxi] ] [[-cluster] ] [[-datacenter] ] [[-baseline] ] [-ExportCSV] [-ExportExcel] [-Patching] [-PassThru] [[-folderPath] ] []

DESCRIPTION Will get patch compliance for a vSphere Cluster, Datacenter or individual ESXi host

RELATED LINKS https://github.com/arielsanchezmora/vDocumentation

REMARKS To see the examples, type: "get-help Get-ESXPatching -examples". For more information, type: "get-help Get-ESXPatching -detailed". For technical information, type: "get-help Get-ESXPatching -full". For online help, type: "get-help Get-ESXPatching -online"

Licensing

Copyright (c) <2017> Ariel Sanchez and Edgar Sanchez

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Installation

The scripts run inside a PowerShell window using PowerCLI modules. Powershell is available in all modern windows OS, with PowerShell core available for Mac and Linux. Make sure you have the latest PowerCLI installed (you can check here for a video on how to install https://blogs.vmware.com/PowerCLI/2017/05/powercli-6-5-1-install-walkthrough.html)

From the video, these are the useful commands you should have completed before installing vDocumentation:

$psversiontable [enter] = gives you the PowerShell version

get-module VMware* -ListAvailable [enter] = Lists all installed PowerCLI modules, if return empty, install PowerCLI

Installing PowerCLI

Find-Module -Name VMware.PowerCLI = checks connectivity to PowerShell Gallery and updates NuGet if needed (yes is default)
Install-Module -Name VMware.PowerCLI -Scope CurrentUser = install PowerCLI as long as you answer Y or A

Execution Policy and Certificate Warnings

Make sure that your execution policy allows you to run scripts downloaded from the internet. You do this with a command run in a powershell window that has been launched with "Run as Administrator"

Set-ExecutionPolicy RemoteSigned

and click Y or A

Unless you have proper certificates in your vSphere environment, some of the data collections may fail silently due to a certificate warning. Run this command so you never have to wonder:

Set-PowerCLIConfiguration -InvalidCertificateAction Ignore

Y is default

Excel Module

While not required, having this module installed is recommended, as you can export direct to Excel. Read about ImportExcel module.

Install-Module ImportExcel -scope CurrentUser

Adding the vDocumentation module

vDocumentation was created as a PowerShell module as well, and it's published in the PowerShell Gallery, so we can use the Install-Module command:

Install-Module vDocumentation -scope CurrentUser

If you can't use the online method, use this manual process:

1 Download the two files inside the vDocumentation folder.
2 Browse to the %USERPROFILE%\Documents\WindowsPowerShell\Modules and copy the files inside a folder named vDocumentation
3 Close all PowerShell windows
4 Launch PowerShell again, you should be able to use the vDocumentation functions now

One method to copy the needed files from Github to your PC using PowerShell:

Execute these lines in a PowerShell window that is in your home directory (tested with PS 5)

mkdir Documents\WindowsPowerShell\Modules\vDocumentation

(new-object Net.WebClient).DownloadString("https://raw.githubusercontent.com/arielsanchezmora/vDocumentation/master/powershell/vDocument/vDocument.psd1") > Documents\WindowsPowerShell\Modules\vDocument\vDocumentation.psd1

(new-object Net.WebClient).DownloadString("https://raw.githubusercontent.com/arielsanchezmora/vDocumentation/master/powershell/vDocument/vDocument.psm1") > Documents\WindowsPowerShell\Modules\vDocument\vDocumentation.psm1

exit