VMware/vSphere/esxcli/Custom Plugins

Custom Plugins
ESXCLI Partner Extensiblity | VMware vSphere Blog - VMware Blogs - http://blogs.vmware.com/vsphere/2012/02/esxcli-partner-extensiblity.html
 * by William Lam
 * "Many vSphere administrators are familiar with the ESXCLI command-line utility that helps manage and configure settings on their ESX and ESXi hosts. With the release of vSphere 5.0, ESXCLI now includes a total of 250 commands that span across various namespaces. One would expect that VMware can easily extend and create new namespaces to expose VMware platform specific functionality. An example of this would be the vcloud namespace that is made available when vCloud Director is installed. What you may not know is, ESXCLI was actually built with a modular and extensible framework from the ground up and can easily be extended by third party providers as well."
 * No instructions though!

-

NOTE: RESTART HOSTD FOR CHANGES TO PLUGINS TO TAKE EFFECT

/etc/init.d/hostd restart

-

VMware Front Experience: How to write your own esxcli plugin - http://www.v-front.de/2013/01/release-esxcli-plugin-to-run-arbitrary.html

-

Documentation - https://vdc-repo.vmware.com/vmwb-repository/sdk_vmkapiddk-2013-vmwb30-ed681d01e7df4111a5f8b1e7910d08a6/doc/#linka7ffebb4150895da6cdd8afd490376de08836e14;vmware.hostextensions/HostExtensions_ESXCLI.4.1.html

-

VIB Package Editor Guide - https://vdc-repo.vmware.com/vmwb-repository/sdk_vmkapiddk-2013-vmwb30-ed681d01e7df4111a5f8b1e7910d08a6/doc/#link5acae8fe22439b3b71b94cacae50bcf0d17fea9f;vmware.hostextensions/HostExtensions_Workbench.3.1.html
 * Host Extensions Development Kit - https://vdc-repo.vmware.com/vmwb-repository/sdk_vmkapiddk-2013-vmwb30-ed681d01e7df4111a5f8b1e7910d08a6/doc/vmware.hostextensions/HostExtensions_Workbench.3.1.html
 * Extending ESXCLI Commands Using the vCLI - https://vdc-repo.vmware.com/vmwb-repository/sdk_vmkapiddk-2013-vmwb30-ed681d01e7df4111a5f8b1e7910d08a6/doc/vmware.hostextensions/HostExtensions_ESXCLI.4.1.html
 * Developing for the ESXi Userworld Environment - https://vdc-repo.vmware.com/vmwb-repository/sdk_vmkapiddk-2013-vmwb30-ed681d01e7df4111a5f8b1e7910d08a6/doc/vmware.hostextensions/HostExtensions_Userworld.5.1.html

Host Extensions - VMware Developer Center - http://developercenter.vmware.com/web/dp/other-programs/host-ext
 * Host-based extensions or plug-ins broaden the ESXi hypervisor platform and give customers a rich set of value-added host management solutions. The Host Extensions Program (HEX) provides partners with development tools and resources for releasing these host-based extensions.

SDKs & APIs - VMware Developer Center - https://developercenter.vmware.com/web/dp/dev-kits/sdks
 * Platform & Compute - Host Extensions SDK - !!LOCKED!!

Documentation - VIB Package Editor Introduction - https://vdc-repo.vmware.com/vmwb-repository/sdk_vmkapiddk-2013-vmwb30-ed681d01e7df4111a5f8b1e7910d08a6/doc/

VMware Front Experience: How to write your own esxcli plugin - http://www.v-front.de/2013/01/how-to-write-your-own-esxcli-plugin.html

Introducing the VIB Author Fling | VMware vSphere Blog - VMware Blogs - http://blogs.vmware.com/vsphere/2012/09/introducing-the-vib-author-fling.html
 * "I’m very excited to announce the new vibauthor fling. This fling is hot off the press and provides the capability to create custom vSphere Installation Bundles (VIBs).  Prior to this fling the VIB authoring tools were only available to VMware partners, this fling now extends this capability to everyone. There are a couple of use cases for creating custom VIBs.  For example, if you are using Auto Deploy and you need to add a custom firewall rule to your host, or you need to make a configuration change that can’t be made using Host Profiles."
 * What’s in a VIB? | VMware vSphere Blog - VMware Blogs - http://blogs.vmware.com/vsphere/2011/09/whats-in-a-vib.html

-

How to write your own esxcli plugin - http://www.vmwaredirectory.com/component/mtree/esx-i/console/how-to-write-your-own-esxcli-plugin
 * "I want to share what you need to know about the esxcli plugin system to be able to write your own plugins."

I finally ended up with the following contents for the esxcli-shell.xml file: 01	 02	 03	 1.0.0 04	   05	  06	    07	      Run any ESXi shell command 08	   09	  10	 11	  12	   13	     14	     Run shell command(s) passed by parameter 15	      16	        17	         Shell command(s) to execute 18	       19	   20	   Specifies a log file to redirect the commands' standard and error output to (see also --errlog) 21	       22	   23	   Specifies a log file to redirect the commands' error output to (overrides --logfile if also set) 24	       25	   26	   Specifies a working directory for the shell command(s) 27	       28	   29	   Append to existing log file(s) (ignored if --logfile and/or --errlog is not also set) 30	       31	       32	      33	       34	       35	      36	      37	       simple 38	      39	     /opt/VFrontDe/esxcli-shell/bin/esxcli-shell.sh $multilist{command,-c,true} $if{workdir,-d "$val{workdir}"} $if{logfile,-l "$val{logfile}"} $if{errlog,-e "$val{errlog}"} $if{lappend,-a} 40	   41	   42	     43	     About the esxcli shell plugin 44	     <input-spec /> 45	      46	       47	      </output-spec> 48	     <has-updates value="false" /> 49	      50	       simple 51	     </format-parameters> 52	     /opt/VFrontDe/esxcli-shell/bin/esxcli-shell.sh -i 53	   54	 55	  56

This is the code of the esxcli-shell.sh script used in the esxcli-shell plugin: 01	#!/bin/sh 02	# 03	TMPSH=/tmp/esxcli-shell.$$ 04	# 05	while getopts :c:d:l:e:ai opt; do 06	  case $opt in 07	   c) echo $OPTARG | sed -e 's/\\\(.\)/\1/g' -e 's/^"\(.*\)"$/\1/' -e "s/^'\(.*\)'$/\1/" >>$TMPSH ;; 08	   d) wdir=$OPTARG ;; 09	  l) logfile=$OPTARG ;; 10	   e) errlog=$OPTARG ;; 11	  a) appendlog=">" ;; 12	   i) about=1 ;; 13	  esac 14	done 15	# 16	echo "<?xml version=\"1.0\" ?>" 17	echo "<output xmlns=\"http://www.vmware.com/Products/ESX/5.0/esxcli/\">" 18	echo -n " <![CDATA[" 19	# 20	if [ "$about" == "1" ]; then 21	  cat <<EOT 22	 23	Esxcli Shell plugin v1.1 by 24	  Andreas Peetz (http://www.v-front.de) 25	... 42	  possibility of such damages. 43	EOT 44	else 45	  oldPWD="$PWD" 46	  [ -n "$wdir" ] && cd "$wdir" 47	  cmd=". $TMPSH" 48	  [ -n "$logfile" ] && cmd="$cmd >$appendlog\"$logfile\"" 49	  if [ -n "$errlog" ]; then 50	     cmd="$cmd 2>$appendlog\"$errlog\"" 51	  else 52	     cmd="$cmd 2>&1" 53	  fi 54	   cat $TMPSH | logger -t "shell[$$]: [${VI_USERNAME} via esxcli]" 55	  ( eval $cmd ) 2>&1 || true 56	  cd "$oldPWD" 57	  rm -f $TMPSH 58	fi 59	echo "]]> " 60	echo " "

Fusion-io ioMemory Custom Plugin Example
/usr/lib/vmware/esxcli/ext/esxcli-fio.xml <?xml version="1.0"?> <plugin xmlns="http://www.vmware.com/Products/ESX/5.0/esxcli/"> 1.0.0

Fusion-io utility CLI

<command path="fio.status"> General information utility for Fusion-io devices.  <parameter name="all" type="flag" required="false" shortname="a"> Report all available information. <parameter name="err-warn" type="flag" required="false" shortname="e"> Report only errors and warnings, with minimal device info. <parameter name="data-volume" type="flag" required="false" shortname="d"> Report the volume of data read and written. <parameter name="unavailable" type="flag" required="false" shortname="u"> Show unavailable fields. Only valid with XML/JSON output format: -f/--format x/j. <parameter name="unavailable-detail" type="flag" required="false" shortname="U"> Show unavailable fields and details why. Only valid with XML/JSON output format: -f/--format x/j. <parameter name="field" type="string-list" required="false" shortname="F"> Print the value for a single field. Requires that a device be specified. Multiple -F options may be specified. <parameter name="list-fields" type="flag" required="false" shortname="l"> List the fields that can be individually accessed with --field and exit. <parameter name="list-devices" type="flag" required="false" shortname="L"> List all the available ioMemory devices on the system. <parameter name="count" type="flag" required="false" shortname="c"> fio-board-count mode: Report the number of Fusion-io boards installed. <parameter name="format" type="string" required="false" shortname="f"> Format output. Must be one of s / x/ j. 's' is standard format (default). 'x' is XML output format. 'j' is JSON output format <enum-value value="s">s</enum-value> <enum-value value="x">x</enum-value> <enum-value value="j">j</enum-value> <parameter name="device" type="string" required="false" shortname="D"> Pathname to the control device (fctx). </input-spec>  </output-spec> <has-updates value="false" />  simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh status $if{all,-a} $if{err-warn,--err-warn} $if{data-volume,--data-volume} $if{unavailable,-u} $if{unavailable-detail,--unavailable-detail} $if{list-fields,-l} $if{count,-c} $if{format,-f"$val{format}"} $if{field,$multilist{field,-F,false}} $if{list-devices,-L} $if{device,"$val{device}"}

<command path="fio.updateiodrive"> Update ioDrive firmware. Note: MUST NOT be used while the ioDrive is attached.  <parameter name="ffffile" type="string" required="true" shortname="F"> pathname to the firmware file <parameter name="force" type="flag" required="false" shortname="f"> force upgrade (bypass all validation); (may result in data loss) <parameter name="bypass-ecc" type="flag" required="false"> bypasses ECC compatibility validation <parameter name="bypass-barrier" type="flag" required="false"> bypasses barrier version validation <parameter name="bypass-uptodate" type="flag" required="false"> bypasses already up to date validation <parameter name="split" type="flag" required="false"> split into virtual controllers <parameter name="merge" type="flag" required="false"> merge virtual controllers <parameter name="device" type="string" required="false" shortname="d"> specify a device to update (ex: /dev/fct0) <parameter name="pretend" type="flag" required="false" shortname="p"> show what updates would be done (firmware will not be modified) <parameter name="list" type="flag" required="false" shortname="l"> list the firmware available in the archive <parameter name="clear-lock" type="flag" required="false" shortname="c"> clears locks placed on a device <parameter name="quiet" type="flag" required="false" shortname="q"> quiet mode - do not show update progress </input-spec>  </output-spec> <has-updates value="false" />  simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh update-iodrive -Q -y $if{quiet,-q} $if{force,--force} $if{bypass-ecc,--bypass-ecc} $if{bypass-barrier,--bypass-barrier} $if{bypass-uptodate,--bypass-uptodate} $if{device,-d "$val{device}"} $if{pretend,-p} $if{split,--split} $if{merge,--merge} $if{list,-l} $if{clear-lock,-c} $if{ffffile,"$val{ffffile}"}

<command path="fio.bugreport"> Problem reporting utility for Fusion-io devices.  <parameter name="dest" type="string" required="false"> Directory to generate the report tar <parameter name="cmds" type="string" required="false"> Additional commands output to include in report. File format: "directory=None:cmd args:timeout=None" <parameter name="data" type="string" required="false"> Additional files to include in report <parameter name="skip-space-check" type="flag" required="false"> Skip check for disk space before collecting logs </input-spec>  </output-spec> <has-updates value="false" />  simple </format-parameters> LOGNAME=$USER /opt/fio/bin/esxcli-fio-script.sh bugreport $if{dest, --dest="$val{dest}"} $if{cmds, --cmds="$val{cmds}"} $if{data, --data="$val{data}"} $if{skip-space-check, --skip-space-check}

<command path="fio.attach"> Fusion-io utility to attach an ioDrive.  <parameter name="device" type="string-list" required="true" shortname="d"> Device node. <parameter name="clean" type="flag" required="false" shortname="c"> Attach only if clean. <parameter name="rescan" type="flag" required="false" shortname="r"> Force a metadata rescan. <parameter name="quiet" type="flag" required="false" shortname="q"> Disable progress print outs. </input-spec>  </output-spec> <has-updates value="false" />  simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh attach -Q $if{quiet,-q} $if{clean,-c} $if{rescan,-r} $if{device,$multilist{device,"",false}}

<command path="fio.detach"> Fusion-io utility to detach an ioDrive.  <parameter name="device" type="string-list" required="true" shortname="d"> Device node. <parameter name="quiet" type="flag" required="false" shortname="q"> Disable progress display. </input-spec>  </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh detach -Q -y $if{quiet,-q} $if{device,$multilist{device,"",false}}

<command path="fio.beacon"> Fusion-io utility to enable or disable the beacon for the card attached to a device node. <input-spec> <parameter name="device" type="string" required="true" shortname="d"> Device node. <parameter name="on" type="flag" required="false"> Enable beacon of device. <parameter name="off" type="flag" required="false"> Disable beacon of device. <parameter name="ppci" type="flag" required="false" shortname="p"> Print the pci bus id of device. </input-spec> <output-spec> </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh beacon $if{on,--on} $if{off,--off} $if{ppci,-p} $if{device,"$val{device}"}

<command path="fio.geterasecount"> Fusion-io utility to report statistics on block erase counts. <input-spec> <parameter name="device" type="string" required="true" shortname="d"> Device node. <parameter name="bad-blocks" type="flag" required="false" shortname="b"> Report on retired blocks. <parameter name="histogram" type="flag" required="false" shortname="H"> Print a histogram of erase counts. <parameter name="summary" type="flag" required="false" shortname="s"> Only show summary of erase count. </input-spec> <output-spec> </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh get-erase-count $if{bad-blocks,-b} $if{histogram,-H} $if{summary,-s} $if{device,"$val{device}"}

<command path="fio.pcicheck"> Fusion-io utility to checks for errors on the PCI bus tree, specifically for ioDrives. It is perfectly normal to see a few correctable errors when initially run. Subsequent runs should only reveal one or two errors for several hours of operation. MUST be used while the driver is loaded. <input-spec> <parameter name="ereport" type="flag" required="false" shortname="e"> Enable PCI-e error reporting. <parameter name="verbose" type="flag" required="false" shortname="v"> Scan every device in the system. <parameter name="findall" type="flag" required="false" shortname="f"> Scan every device in the system. <parameter name="retrain" type="flag" required="false" shortname="r"> Force link to retrain. <parameter name="disable" type="string" required="false" shortname="d"> 1 disable link, or 0 bring link up. </input-spec> <output-spec> </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh pci-check $if{ereport,-e} $if{verbose,-v} $if{findall,-f} $if{retrain,-r} $if{disable,-d "$val{disable}"}

<command path="fio.readlebmap"> Fusion-io utility which reads the media event log out of the device. <input-spec> <parameter name="device" type="string" required="true" shortname="d"> ioDrive control node, e.g. /dev/fct0. <parameter name="file" type="string" required="false" shortname="f"> Name of the output file to generate. </input-spec> <output-spec> </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh read-lebmap $if{device, "$val{device}"} $if{file, "$val{file}"}

<command path="fio.format"> Fusion-io format utility. [B,K,M,G,T,P,%%] are units: Bytes, KBytes, MBytes, GBytes, TBytes, PBytes and percent. <input-spec> <parameter name="device" type="string" required="true" shortname="d"> ioDrive control node, e.g. /dev/fct0. <parameter name="block-size" type="string" required="false" shortname="b"> Set the block (sector) size, in Bytes or KiBytes (base 2) <parameter name="device-size" type="string" required="false" shortname="s"> Size to format device where max size is default capacity. <parameter name="overformat" type="string" required="false" shortname="o"> Overformat device size where max size is maximum physical capacity. <parameter name="sparse" type="flag" required="false" shortname="e"> Sparse format. <parameter name="sparse-logical-sector-count" type="string" required="false" shortname="l"> Sparse format optional logical sector count (physical size is defined by -s option). Default = maximum that can be addressed. % means a percentage of the default. <parameter name="enable-atomic-writes" type="flag" required="false" shortname="A"> Make atomic writes feature available on the device. <parameter name="enable-persistent-trim" type="flag" required="false" shortname="P"> Make persistent trim feature available on the device. <parameter name="slow-rescan" type="flag" required="false" shortname="R"> Disable fast rescan on unclean shutdown to reclaim some capacity. <parameter name="force" type="flag" required="false" shortname="f"> Force formatting outside standard limits. <parameter name="quiet" type="flag" required="false" shortname="q"> Quiet mode - do not print progress. </input-spec> <output-spec> </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh format -Q -y $if{quiet,-q} $if{block-size,-b "$val{block-size}"} $if{device-size,-s "$val{device-size}"} $if{overformat,-o "$val{overformat}"} $if{enable-persistent-trim, -P} $if{slow-rescan, -R} $if{sparse,-e $if{sparse-logical-sector-count,"$val{sparse-logical-sector-count}"}} $if{force, -f} $if{enable-atomic-writes,-A} $if{device, "$val{device}"}

<command path="fio.version"> Version of the Fusion-io utilities. <input-spec> </input-spec> <output-spec> </output-spec> <has-updates value="false" /> <format-parameters> simple </format-parameters> /opt/fio/bin/esxcli-fio-script.sh status -v

/opt/fio/bin/esxcli-fio-script.sh
 * 1) !/bin/sh


 * 1) Copyright (c) 2013 Fusion-io, Inc. All rights reserved.
 * 2) No use, or distribution, of this source code is permitted in any form or
 * 3) means without a valid, written license agreement with Fusion-io. Please
 * 4) refer to the included "License" or "License.txt" file for terms and
 * 5) conditions regarding the use and redistribution of this software.
 * 1) refer to the included "License" or "License.txt" file for terms and
 * 2) conditions regarding the use and redistribution of this software.

echo "<?xml version=\"1.0\" ?>" echo "<output xmlns=\"http://www.vmware.com/Products/ESX/5.0/esxcli/\">" echo -n " <![CDATA["
 * 1) esxcli requires that all output be wrapped in xml

utility='/opt/fio/bin/fio-'$1

shift

$utility $@ 2>&1

echo "]]> " echo " "