For use only by VMware and VMware Solution Providers

Not a Customer Deliverable

PowerActions v1.0.1

PowerActions Documentation

PowerActions v1.0

Page 2 of 14

Version History

Date Doc Ver Author Description

30 Sept 2014 1.2 Alan Renouf Updated for PowerActions 1.1 release and including install/uninstall instructions

18 Sept 2014 1.1 Alan Renouf Updated requirements and format for shared script and security

2 Sept 2014 1.0 Alan Renouf Updated docs with new format, further detail and screen captures

26 Aug 2014 0.5 Martin Marinov Initial draft docs

PowerActions Documentation

PowerActions v1.0

Page 3 of 14

Contents

1. Overview .......................................................................................... 4

1.1 Description of solution .................................................................................................... 4

2. Installation ........................................................................................ 5

2.1 Prerequisites .................................................................................................................. 5

2.2 Installation process ........................................................................................................ 5

2.3 What is installed ............................................................................................................. 9

2.4 Security .......................................................................................................................... 9

2.5 Frequently encountered problems during installation. ................................................. 10

3. Using the console .......................................................................... 10

4. Using the script-defined action functionality ................................... 11

4.1 What is a script............................................................................................................. 11

4.2 Own and shared scripts ............................................................................................... 11

4.3 Rendering the script output .......................................................................................... 11

5. Creating a new script for the “My Script” area ................................ 11

6. Creating a new script for the “Shared Scripts” area ........................ 12

6.1 The script format explained .......................................................................................... 12

6.2 Script input parameter type .......................................................................................... 12

6.3 Report formatting options ............................................................................................. 12

6.4 Name and description metadata .................................................................................. 13

6.5 Executing a script ......................................................................................................... 13

6.6 Tips & tricks when using the library ............................................................................. 13

6.7 Example script.............................................................................................................. 14

PowerActions Documentation

PowerActions v1.0

Page 4 of 14

1. Overview

1.1 Description of solution PowerActions integrates the vSphere Web Client and PowerCLI to provide complex automation

solutions from within the standard vSphere management client.

PowerActions is deployed as a plugin for the vSphere Web Client and will allow you to execute PowerCLI

commands and scripts in a vSphere Web Client integrated Powershell console.

Furthermore administrators will be able to enhance the native WebClient capabilities with actions and

reports backed by PowerCLI scripts persisted on the vSphere Web Client. Have you ever wanted to

“Right Click” an object in the web client and run a PowerCLI script? Now you can!

For example I as an Administrator will be able to define a new action for the VM objects presented in

the Web client, describe/back this action with a PowerCLI script, save it in a script repository within the

Web client and later re-use the newly defined action straight from the VM object context (right click)

menu.

Or I as an Administrator can create a PowerCLI script that reports all VMs within a Data Center that have

snapshots over 30 days old, save it in a script repository within the Web client and later execute this

report straight from the Datacenter object context menu.

Or better yet, why not share your pre-written scripts with the rest of the vSphere admins in your

environment by simply adjusting them to the correct format and adding them to the shared script

folder.

PowerActions Documentation

PowerActions v1.0

Page 5 of 14

2. Installation

2.1 Prerequisites The following is a list of prerequisites needed for using PowerActions, please ensure you meet these requirements as other versions may not have been tested and cannot be guaranteed to work.

VMware vSphere 5.1 or later PowerShell Host Machine

Windows 2003 Server or newer (*)/Vista or newer

.NET framework 4.0*

PowerShell V1, V2 or V3 (V4 not supported)

PowerCLI version supporting your current VMware vSphere version * Note: .NET framework 4.5 is not supported. Windows 2012 Server/Windows 8 and Windows 8.1 come with 4.5 by default, so a downgrade to .Net Framework 4.0 is required on these versions of Windows.

Administrative privileges (registering a service with VMware Lookup Service and creating a user for SSO) are required for installation, but not for use of the product.

Prior to installation, ensure that the PowerShell Host machine and the machine hosting the VMware Lookup Service are synced via the same time source, otherwise cryptic error messages may appear.

2.2 Installation process Please follow the below steps to ensure PowerActions is installed correctly in your environment:

Download the PowerActions MSI file and store on the machine to be used as the PowerShell host, launch the MSI file.

PowerActions Documentation

PowerActions v1.0

Page 6 of 14

Click Next on the welcome screen

Read and accept the EULA and click Next

PowerActions Documentation

PowerActions v1.0

Page 7 of 14

Select Browse to select a new location if required, Click Next

Enter the local machine's primary network identifier (IP address/hostname) and port. The PowerShell host service will listen on this address. The vSphere Web Client instances that are targets of the fling

PowerActions Documentation

PowerActions v1.0

Page 8 of 14

should be able to connect to this machine by this address. A firewall rule will automatically be created which allows connections on this port.

Enter the VMware lookup service address and credentials. The lookup service's standard location is https://<address-of-vCenter-server-machine>:7444/lookupservice/sdk . The credentials of an SSO Administrator are required in order to register the PowerShell host service and the vSphere Web Client plugin to the lookup service and to create a solution user for PowerActions.

Click Install to install PowerActions now all configuration has been provided and click Finish once the installation has been completed.

PowerActions Documentation

PowerActions v1.0

Page 9 of 14

The PowerCLI Console and PowerCLI Scripts section should now be available via the web client.

2.3 What is installed On the Windows machine that runs the PowerShell host service:

A folder is created under C:\ProgramData\VMware\myNGC. It has a couple of sub-folders: o Logs contains the log files of the PowerShell host service o Scripts contains the "shared" scripts (see the Script Library section of this document).

A machine user (service user) under whose credentials the PowerShell host service will run. Change of state concerning VMware lookup service/SSO:

A solution user, named "myNGC" is registered with VMware SSO. This user is not granted special privileges.

Two services are registered with lookup service: the PowerShell host service and the vSphere Web Client plugin. Both services are owned by the aforementioned solution user.

2.4 Security

The SSO admininistrator credentials provided at installation are only used during installation, these are not saved anywhere. These are only provided so that the back-end service can register with vCenter (this allows the UI plug-in to locate the service). The registration process creates a dedicated "PowerAction SSO Solution User" that is the owner of the registration. All post-installation interaction with the SSO service uses this solution user.

PowerActions Documentation

PowerActions v1.0

Page 10 of 14

The password for the “PowerAction SSO Solution User” is prepopulated by VMware but in some circumstances this may not meet your security requirements and you may receive a similar error to the below: Error 26402. Failed to create user due to invalid password. (-2147022651 MyNgcServiceUser )

If this is the case you can specify a password to use through the MYNGCSERVICEPASSWORD MSI property, e.g.: msiexec /i PowerActions_2121041.msi MYNGCSERVICEPASSWORD=Th!$R0CK$!

2.5 Frequently encountered problems during installation. [Q] During installation, I receive an "invalid principal myNGC" error. [A] This is most probably due to an existing user with the same name, either due to another existing installation on the same lookup service instance, or due to the user having been created by other means. [Q] Installation fails after inputting the credentials for the lookup service, yet the credentials are valid. [A] This is most probably due to a clock skew between the machine you're installing the fling on and the VMware Lookup Service/SSO machine. [Q] After installation the Icons for PowerCLI Console and PowerCLI Scripts are not shown in the web client. [A] Restart the web client service or server to allow the service to register itself.

3. Using the console

After PowerActions is successfully installed, you can expect a "PowerCLI console" link to appear in the vSphere Web Client's side menu and home page. The console has separate input and output panels. When a command is executed, the results of its execution are displayed in the output panel. During execution, a spinner is displayed in the bottom right corner of the output panel.

Some useful information on using the console:

The execution of the first command may take longer than expected - it has to wait for logging in the VC.

There is a pop-up that contains the standard keyboard shortcuts for using the console.

The CLS command is not implemented and will throw an error. However, there is a button which clears the output pane.

When a prompt is displayed, the standard keyboard shortcuts (as well as the enter and escape keys) should still work, so no mouse clicking is required to answer prompts.

The console has the native PowerShell autocomplete functionality, accessed by using the tab button.

The console supports command history (up to N commands). The Page Up and Page Down buttons are used to cycle through the command history.

When PowerShell prompts for an object, if the requested type is a known vSphere type, an object selector is available.

PowerActions Documentation

PowerActions v1.0

Page 11 of 14

4. Using the script-defined action functionality

A "PowerCLI Scripts" link is available after successfully installing PowerActions. Clicking this menu item will lead to a master-details view of the defined scripts.

4.1 What is a script An action defined by a script is, in essence, a PowerCLI scriptblock, which accepts a known VI object type as its first parameter. A script can be interactive and query the user for additional input after its execution has started.

4.2 Own and shared scripts On the top left of the script library, there is a drop-down menu with two options: "My scripts" and "Shared scripts".

"My scripts" should contain the scripts that the user themselves has created. These scripts are only

visible to the user that has created them, and are completely editable by said user.

"Shared scripts" contains scripts which are read-only through the UI and are visible to, and

executable by all users. They are backed by ".ps1" files located in the folder. Additional scripts can be added there by putting new files in said folder. The exact format of the files is specified in section 4.5. A restart of the PowerShell host service is needed for the newly added scripts to be visible to users.

4.3 Rendering the script output The fling allows for rendering the output of the script in two formats: action and report.

4.3.1 Action

All the output is rendered as text in a smaller console window.

4.3.2 Report

The output is rendered in a standard web client grid. The output is expected to be homogeneous (otherwise, the fields of the first object are selected as a schema). If the type of the output objects is a managed object, or is a custom object with only one managed object field, then the result rows are first-class web client objects, and a context menu can be invoked on them, for either further PowerCLI operations, or native vSphere Web Client operations.

5. Creating a new script for the “My Script” area

A new script can be created by clicking the new script icon in the script list. A wizard will be invoked. Argument type: on the first page, the argument type has to be input. Checking the "Expects multiple objects" checkbox will make the script show in the execution dialog for multiple context objects of the selected type in the web client. Otherwise, the script will only be displayed when invoking the action on a single object of the selected type. Name and description: you can input the name, description and output type on this page.

PowerActions Documentation

PowerActions v1.0

Page 12 of 14

Script body: the script block's body can be edited on this page. It has a pre-generated params statement, reflecting the script's input object type, and, optionally, a report meta-annotation (see 2.5, "The script format explained").

“My scripts” are (currently) stored via the web client’s persistence service – it is usually a file system database under WEBCLIENT_ROOTSerenityDBserenity{user}myngc_library* (with WEBCLIENT_ROOT depending on whether the web client is deployed on a Windows or Linux machine).

6. Creating a new script for the “Shared Scripts” area

A shared script is backed by a .ps1 file in the Scripts ProgramData folder of the PowerShell host. Because it is self-contained, its name and description must be specified in the script itself (see the following section).

6.1 The script format explained The following metadata of a script can be retrieved from the script body (in the case of a shared script, this is all the metadata):

Its input parameter type

Its output format and additional output formatting options

Its name and description

6.2 Script input parameter type All information on the script's input is inferred from its params statement. By convention, the type of its first argument is the type of objects the script is available for. Any additional parameters will be prompted for after selecting the script for execution. They must be marked as mandatory.

6.3 Report formatting options In the first comment block of the script, if the ".MYNGC_REPORT" statement is present, the script will be rendered as a report (see section 4.3.2). It may, or may not, be followed by additional formatting options: the list of columns to display the report and the column to be designated as a key. The columns to display in the report may not be explicitly specified. Then the following strategy is used:

If the base type of the row's PSObject is a VI object,

If the base type of the row's PSObject is a primitive type, a single column with a field corresponding to the object is displayed.

Otherwise, all the object's fields are displayed as rows. The "key" column is the column whose value will be used to identify the row - invoking a context menu on said row will create a context menu for the object that is the column's value, if it is a managed object. If this value is not present, the context object for the row is:

If the base type of the row's PSObject is a VI object, the object itself is used as a context object for the column.

If the row is a PSCustomObject, and it has exactly one field which is a managed object, it is used as a context object for the column.

Specifying the key column is done by adding a KEY(<column-name>) line. The grammar for the report statement (in Backus-Naur form) is:

PowerActions Documentation

PowerActions v1.0

Page 13 of 14

report-statement := <report-header> | <report-header><EOL><report-options> report-options := <report-columns> | <report-columns><EOL><key-column> report-columns := <report-columns><EOL><column-name> | "" key-column := KEY(<column-name>) report-header := .MYNGC_REPORT

Examples of valid report statements:

.MYNGC_REPORT KEY(Host)

.MYNGC_REPORT VM Host Cluster

.MYNGC_REPORT Host Cluster ParentFolder KEY(ParentFolder)

6.4 Name and description metadata A script's name and description can be specified in the header as well. The name is found under the .LABEL annotation, and the description is found under the .DESCRIPTION annotation. For example:

<# .LABEL Power off VM .DESCRIPTION Powers off said virtual machine. #>

Shared scripts should at least contain a .LABEL declaration.

6.5 Executing a script A script can be executed on an object by invoking the context menu on an object, selecting the PowerCLI sub-menu and clicking on "Execute Script...". A pop-up dialog with the available scripts for execution for this object is displayed. Next to the script is an icon denoting its output type. When executing a script, it may interact with the user and prompt for additional input, using the same user interface as the console prompts.

6.6 Tips & tricks when using the library The script list part of the library, as well as the scripts-to-execute list have filtering functionality, which can be used for quickly focusing on the needed script(s).

PowerActions Documentation

PowerActions v1.0

Page 14 of 14

6.7 Example script The following example enables a right click report that outputs the Hosts selected to the screen.

<#

.MYNGC_REPORT

.LABEL

Sample Example Script

.DESCRIPTION

Example script to use as template.

#>

param

(

[Parameter(Mandatory=$true)]

[VMware.VimAutomation.ViCore.Types.V1.Inventory.VMHost]

$vhost

);

$vhost

7. Uninstall Process

If you wish to uninstall PowerActions from the PowerShell host and from the vSphere Web Client please uninstall from the “Programs and Features” area of the PowerShell Host, select PowerActions and Uninstall. 'My Scripts' will be preserved for all users. In order to preserve shared scripts, do a backup of the '%ProgramData%\VMware\myNGC\Scripts\' folder.

8. Upgrade Process

If you already have PowerActions installed, in order to upgrade, you must first uninstall the current version as per the steps above and then do a fresh install of the new version. 'My Scripts' will be preserved for all users. In order to preserve shared scripts, do a backup of the '%ProgramData%\VMware\myNGC\Scripts\' folder.