Installation and configuration guide

Introduction

This wiki page contains information about how to setup and configure WebCommander server.

Although a setup script is provided to automate all these steps, the information is helpful for WebCommander users or developers to understand how it works.

The content of the page will be updated from time to time.

Install Windows Server 2012 R2 or 2008 R2

• Windows Server 2012 R2 and 2008 R2 are recommended and tested to host WebCommander.
• Either VM or physical machine works.
• For an installation guide, please refer to http://technet.microsoft.com/en-us/library/jj134246.aspx

Install dotNet 4.5.2 on Windows 2008 R2

• dotNet 4.5.2 is required to install Powershell 4.0
• It could be downloaded from http://download.microsoft.com/download/E/2/1/E21644B5-2DF2-47C2-91BD-63C560427900/NDP452-KB2901907-x86-x64-AllOS-ENU.exe
• Please note that WebCommander provides installDotNet service to automatically install it.

Install Powershell 4.0 on Windows 2008 R2

• It could be downloaded from http://www.microsoft.com/en-us/download/details.aspx?id=40855
• Please note that WebCommander provides installPowershell4 service to automatically install it.

Install IIS

• For an installation guide, please refer to http://www.iis.net/learn/get-started/whats-new-in-iis-8/installing-iis-8-on-windows-server-2012
• Make sure IIS Management Service is also installed.
• The installation could also be done via the Powershell cmdlet below

Install-WindowsFeature Web-Server -IncludeManagementTools -IncludeAllSubFeature

Install PHP

• Download PHP installer from http://php.iis.net
• Run the installer with default options.

Install PowerCLI

• Download the latest released version of PowerCLI from https://www.vmware.com/support/developer/PowerCLI/index.html
• Run the installer to install all components
• If the installer requires dotNet 3.5, add it to the server by following http://www.azurecurve.co.uk/2013/06/offline-install-of-dotnet-3-5-on-windows-server-2012/ and then re-run the installer.

Configure Powershell

• Please note that Windows Server 2012 has two versions of Powershell, x86 and x64. WebCommander only uses x86 so far because there is only x86 PHP for IIS.
• Open x86 Powershell console and run the commands below Set-ExecutionPolicy Unrestricted -Force
• Add the following lines to x86 Powershell profile. It's located at C:\Windows\SysWOW64\WindowsPowerShell\v1.0\profile.ps1. If not exist, create it.

[Reflection.Assembly]::LoadWithPartialName('system.web') | out-null add-pssnapin vmware* -ea SilentlyContinue $env:defaultPassword = 'replace this with a real password'

• The last line above shows that WebCommander stores a default password in an environment variable named defaultPassword. Consequently, whenever a Powershell session is created, the environment variable is set. Powershell scripts can access the variable as illustrated below

$serverPassword = $env:defaultPassword

Install WebCommander

• Download WebCommander package from https://github.com/vmware/webcommander/archive/master.zip
• WebCommander will be added into Github as well. Once done, I'll update this wiki page.
• Extract the package to C:\WebCommander with 7-zip. Please note that Windows may block Powershell scripts from running if the package is extracted with Windows Explorer. To solve this problem, either to unblock those scripts or set execution policy to bypass.

• Open IIS Manager, delete or disable the default website.
• Add a new website for WebCommander as illustrated

• If no authentication is required, make sure to configure "connect as administrator". Otherwise keep the setting as "pass-through authentication"

Configure Windows Authentication on IIS

• Make sure Windows Authentication has been installed with IIS.

• Open IIS Manager, select WebCommander site and double click Authetication.

• Enable Windows Authentication, and disable the others.

• With Windows Authentication, the only way to log out an authenticated session is to completely close the browser.

Configure Advanced Logging on IIS

• Download and install Advanced Logging Extension for IIS from http://www.microsoft.com/en-us/download/confirmation.aspx?id=7211

• Open IIS Manager, select WebCommander site and double click Advanced Logging.

• Disable the default log.

• Add 3 logging fields as illustrated.

• Add a log definition as illustrated.

Add a new script in WebCommander

• Put the Powershell script under C:\WebCommander\Powershell or its sub folders.
• Edit C:\WebCommander\powershell_def.xml by adding the following codes: ** Command name must be unique. ** Script path is calculated from C:\WebCommander\Powershell. If the file is located at C:\WebCommander\Powershell\myFolder\myScript.ps1, just input "myFolder\myScript". Don't include ".ps1". ** All parameters of the script must be defined. ** If a parameter is optional, set optional="0", otherwise optional="1". ** There are 5 types of parameter: *** Text which is the default type *** Password *** File which is used to upload a file *** Option which is selectable from a drop down list *** SelectText which is similar to Option but all inputting a custom value

<command name="myCommand" description="my command description" developer="developer email alias">
    <script>myScriptPath</script>
    <parameters>
        <parameter optional="0" name="parameter1" description="description1" />
        <parameter optional="0" name="parameter2" description="description2" />			
        ...
    </parameters>	
</command>

• The following codes must be added in myScript.ps1 after param section. This is because webcmd.php encodes parameters to handle special characters.

foreach ($paramKey in $psboundparameters.keys) {
	$oldValue = $psboundparameters.item($paramKey)
	$newValue = [system.web.httputility]::urldecode("$oldValue")
	set-variable -name $paramKey -value $newValue
}

Remove a script

• Remove or rename the Powershell script
• It's not necessary to remove the corresponding codes from webcmd.xml. When webcmd.php parses the XML file, it doesn't display a command if its script couldn't be found.