Chapter 1. New and Changed Information for this Release

New and Changed Information for this Release

Chapter 2. Overview

Cisco UCS Director PowerShell Agent

Chapter 3. Installation of Cisco UCS Director PowerShell Agent

Prerequisites

Downloading Cisco UCS Director PowerShell Agent

Installing Cisco UCS Director PowerShell Agent

Updating Authentication Properties

Configuring the Firewall

Enabling WinRM and WinRS

Chapter 4. Configuring Cisco UCS Director PowerShell Agent

Adding PowerShell Agent to Cisco UCS Director

Verifying Connectivity with Cisco UCS Director

Troubleshooting Connectivity with Cisco UCS Director

Executing a Cisco UCS Director PowerShell Command on a Target Server

Example: Executing a PowerShell Agent Command on a Target Server

Example: Setting Up PowerShell Agent and Running a Test Task

Preface

Audience

Conventions

Related Documentation

Documentation Feedback

Obtaining Documentation and Submitting a Service Request

Copyright Page

Chapter 1. New and Changed Information for this Release

- New and Changed Information for this Release

New and Changed Information for this Release

No significant changes were made to this guide for the current release.

Chapter 2. Overview

This chapter contains the following sections:

- Cisco UCS Director PowerShell Agent

Cisco UCS Director PowerShell Agent

Cisco UCS Director PowerShell Agent (PowerShell Agent) is a lightweight, Microsoft Windows service application that provides the ability to manage applications that expose Windows PowerShell based northbound API calls. The PowerShell Agent acts as an interfacing layer between Cisco UCS Director and applications such as Microsoft System Center Virtual Machine Manager (SCVMM), that is managed through Windows PowerShell. After you have installed and started the PowerShell Agent, you can manage it from Cisco UCS Director.

Note

The PowerShell Agent consumes minimum memory or CPU cycles because it relays the requests and responses back and forth between Cisco UCS Director and Microsoft SCVMM (or other PowerShell enabled applications).

Chapter 3. Installation of Cisco UCS Director PowerShell Agent

This chapter contains the following sections:

- Prerequisites

- Downloading Cisco UCS Director PowerShell Agent

- Installing Cisco UCS Director PowerShell Agent

- Updating Authentication Properties

- Configuring the Firewall

- Enabling WinRM and WinRS

Prerequisites

Before you install Cisco UCS Director PowerShell Agent, make sure that the following software has been installed on the machine:

- Supported Windows operating system

- Supported .NET Framework (Full Package)

- Supported Windows PowerShell

For more information about the system requirements and supported software, see the Compatibility Matrix for Cisco UCS Director.

Note

Cisco UCS Director executes scripts (commandlets) on the target server via remote execution. The target server's northbound PowerShell APIs must support remote invocation.

Downloading Cisco UCS Director PowerShell Agent

You download the installer for PowerShell Agent from Cisco UCS Director.

Step 1

In Cisco UCS Director, choose Administration > Virtual Accounts.

Step 2

Choose the PowerShell Agents tab.

Step 3

Click the Download Installer button.

Step 4

Review the list of installation requirements in the Download Agent Installer dialog box and ensure that you have them available on the target computer where you plan to install Powershell Agent.

Step 5

Click Submit.
The PSASetup.exe file is downloaded to the default download folder on the target computer.

What to Do Next

Install Cisco UCS Director PowerShell Agent on the target computer.

Installing Cisco UCS Director PowerShell Agent

Installing a newer version of the PowerShell Agent requires that you uninstall the older version first. To remove the older version of PowerShell Agent, stop the Cisco PSA Service first and then uninstall the agent.

Note

If you do not install the new version of PowerShell Agent for Cisco UCS Director, Release 5.5, the Execute Power Shell Task and the Execute Command options on the PowerShell Agents tab will not work correctly.

Before You Begin

You need system administrator privileges to complete this task.

Step 1

If necessary, copy the PSASetup.exe that you downloaded from Cisco UCS Director to your target computer.

Step 2

Double-click the PSASetup.exe file.

Step 3

In the Preparing to Install screen, click Next.

Step 4

In the Ready to install the Program screen, click Install.
The Installing Cisco PSA Service screen displays during the installation. When the installation is complete, the InstallShield Wizard Completed screen displays.

Step 5

Click Finish.
The PowerShell Agent is installed to the C:\Program Files (x86)\Cisco Systems\Cisco PSA Service folder. This folder is referred to as %AGENT_INSTALL_FOLDER% in the remainder of the document.

Step 6

On your computer, choose Start, type services.msc in the text field, and press the Enter key.
A list of current services displays. Verify that the Cisco PSA Service is listed and is currently running.

What to Do Next

Configure Cisco UCS Director PowerShell Agent.

Updating Authentication Properties

The PowerShell Agent uses port 43891 (default) and it also uses a predefined authentication/access key to communicate with Cisco UCS Director. You can change these values, if needed, by modifying a properties file. The properties (XML) file is located in the following directory:

%AGENT_INSTALL_FOLDER%/props/properties.xml.

Before You Begin

You should download and successfully install the Cisco UCS Director PowerShell Agent installation program.

Step 1

Use a text editor to open the properties.xml file.

Step 2

Edit the authKey entry.

Step 3

Edit the serverPort entry.

Step 4

Save the file.
Note:
When the PowerShell Agent is added to Cisco UCS Director, the port number and access key values must match the values that are specified in the PowerShell Agent. Cisco UCS Director cannot able to communicate with the PowerShell Agent if the entries do not match

Step 5

(Optional)Restart the Cisco UCS Director PowerShell Agent service if you modify any of the properties in the properties.xml file. This can be done from the Services snap-in (Start > Services.msc)

What to Do Next

Configure your firewalls.

Configuring the Firewall

The PowerShell Agent listens for incoming requests on port 43891 by default. Your machine's firewall needs to be configured so as to allow incoming TCP requests on port 43891 (or any port that you choose to use).

Enabling WinRM and WinRS

To accept remote PowerShell commands, you must enable Windows Remote Management (WinRM) for Windows Server 2008 R2, 2012 or 2012 R2. Once you enable the WinRM, the interoperability of hardware and operations systems is enabled to work with the Windows Remote Shell (WinRS) command-line tool on your target server and the target server hosts.

Before You Begin

The PowerShell Agent only executes the cmdlets and scripts on the target server in a PowerShell remote session. It requires the WinRM configuration to accept the remote session. This is a Windows PowerShell remote session requirement

Step 1

On your host(s), open a command prompt, and enter winrm quickconfig.
Note:
Configuring WinRM over HTTP or HTTPS depends on the requirements of the specific environment. HTTPS is only necessary if a secure connection is required. Instructions on configuring HTTPS communication is available at the following URL: Click Here

The following messages appear:

WinRM is not set up to allow remote access to this machine for management.
The following changes must be made:

Create a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine.
Enable the WinRM firewall exception.

Make these changes [y/n]?

Step 2

Enter y. WinRM is updated for remote management, a listener is created to accept requests, and the firewall exception is enabled:

Make these changes [y/n]? y

WinRM has been updated for remote management.

Created a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine.
WinRM firewall exception enabled.

Step 3

Verify that WinRS is enabled by entering the winrm g winrm/config command at a command prompt.

Step 4

Configure the value " * " in the TrustedHosts table of WinRM by entering the winrm set winrm/config/client @{TrustedHosts="*"} command.
Note:
Adding the value " * " to the TrustedHosts table allows all hosts to be trusted or only add specific trusted IP addresses of target servers to the table.

What to Do Next

Make sure that the domain account used to connect the target server belongs to the local administrator group for the target server hosts.

Chapter 4. Configuring Cisco UCS Director PowerShell Agent

This chapter contains the following sections:

- Adding PowerShell Agent to Cisco UCS Director

- Verifying Connectivity with Cisco UCS Director

- Troubleshooting Connectivity with Cisco UCS Director

- Executing a Cisco UCS Director PowerShell Command on a Target Server

- Example: Executing a PowerShell Agent Command on a Target Server

- Example: Setting Up PowerShell Agent and Running a Test Task

Adding PowerShell Agent to Cisco UCS Director

After PowerShell Agent is installed and running, you must add it to Cisco UCS Director. You must set up the virtual account (for example, an SCVMM account) to use the PowerShell Agent for inventory collection and other management functions.

Step 1

On the menu bar, choose Administration > Virtual Accounts > PowerShell Agents.

Step 2

Click Add. In the Add Agent dialog box, complete the following fields.

Name

Description

Agent name field

The name of the PowerShell Agent.

Agent Address field

The IP address or FQDN (Fully Qualified Domain name) of the PowerShell Agent.

Agent Access Port field

The port assigned to the PowerShell Agent.

Note:   The default port address is 43891. These values are pre-populated with default values. The PowerShell Agent is pre-configured to use these values and UCS Director must have matching values. These values can be changed on the Agent, but UCS Director must always use them as well.

Access key field

The default access key assigned to the PowerShell Agent.

Note:   These values are prepopulated with default values. The PowerShell agent is preconfigured to use these values and Cisco UCS Director must have matching values. These values can be changed on the PowerShell Agent, but Cisco UCS Director must always use them as well.

Description field

The description of the PowerShell Agent.

Step 3

Click Submit.

What to Do Next

Verify connectivity between Cisco UCS Director and the PowerShell Agent.

Verifying Connectivity with Cisco UCS Director

After the PowerShell Agent is added, you can check the connectivity between Cisco UCS Director and the PowerShell Agent.

Step 1

On the menu bar, choose Administration > Virtual Accounts > PowerShell Agents.

Step 2

Click the Test Connect icon.
Cisco UCS Director displays a success message if it can communicate with the PowerShell Agent.

If Cisco UCS Director cannot communicate with the PowerShell Agent, see

What to Do Next

Execute the Cisco UCS Director PowerShell command on the target server.

Troubleshooting Connectivity with Cisco UCS Director

Problem

You can experience a failed test connection with Cisco UCS Director. This problem can occur even though you successfully installed and configured the PowerShell Agent, and there is no issue with the network connectivity between PowerShell Agent and Cisco UCS Director.

Note

This problem can happen with Windows Server 2012 R2 or other versions that use advanced cipher suites for https communication.

Symptom

When you check the PowerShell Agent logs in the PowerShell Agent server, you will find an SSPI failed with inner exception error. See a sample error message below:

2014-08-20 14:44:16,832 [6] ERROR cuic.ClientConnection[null] -
Exception: A call to SSPI failed, see inner exception.

2014-08-2014:44:16,832 [6] DEBUG cuic.ClientConnection[null] - Inner exception: The message received was unexpected or badly formatted.

2014-08-2014:44:16,832 [6] DEBUG cuic.ClientConnection[null] - Authentication failed - closing the connection.

Cause

The test connection fails because of the Microsoft update, in which, new TLS cipher suites are added and cipher suite priorities are changed in Windows RT 8.1, Windows 8.1, and Windows Server 2012 R2. See Microsoft kb article 2929281 for further information on this update.

Solution

To resolve the problem, you must modify the SSL cipher suite group policy setting. Follow the steps listed below:

1. At a command prompt, enter gpedit.msc to open your group policy editor.

2. Expand Computer Configuration > Administrative Templates > Network, and then click SSL Configuration Settings.

3. Under SSL Configuration Settings, click the SSL Cipher Suite Order setting.

4. In the SSL Cipher Suite Order pane, scroll to the bottom of the pane.

5. Follow the instructions labeled How to modify this setting.

It is necessary to restart the computer after modifying this setting for the changes to take effect.

Executing a Cisco UCS Director PowerShell Command on a Target Server

Cisco UCS Director provides a mechanism to test connectivity to a target server through the PowerShell Agent (end-to-end connectivity).

Step 1

On the menu bar, choose Administration > Virtual Accounts > PowerShell Agents.

Step 2

Click the Execute Command icon.

Step 3

In the Execute PowerShell Command dialog box, complete the following fields:

Name

Description

Target Machine IP field

The IP address of the target machine.

User ID field

The unique ID assigned to the user.

Password field

The assigned password.

Domain field

The current server domain.

Commands/Script field

The field to enter your command to execute.
Note:   Commands/scripts up to 64 kb in size are allowed.

Command Output field

The results of the execution appear in this field.

Step 4

Click Execute. The Command Output window displays the execution results.

Step 5

Click Close.

Example: Executing a PowerShell Agent Command on a Target Server

PowerShell Agent commands can be used in a workflow orchestration in Cisco UCS Director. A workflow can use a task that executes PowerShell commands against a target server.

A workflow, for example, can consist of the following Orchestrator elements:

- Start icon

- Execute PowerShell Command task icon

- Both Completed (Success) task and Competed (Failed)-task icons

The Execute PowerShell Command, for example, could use the following inputs:

- PowerShell Agent

- Target Server's credentials (IP address, username and password, and domain)

- Commands or Scripts of up to 64 kb.

Note

Alternatively, you can provide the path to a PowerShell script on the target server (for example: C:\scripts\DoSomething.ps1) instead of providing a series of commands. The PowerShell Agent executes the script as long as it exists at the specified path on the target server.

In the above example, the PowerShell command is mapped to a user input, while the rest of the inputs are pre-configured within the task itself. When you execute the workflow in Cisco UCS Director, you are prompted to enter the PowerShell Agent commands to run on a target server. Use a ";" to separate multiple commands (for example, Hostname; Get-Process). Cisco UCS Director runs the commands against the target server and displays the output as an XML string in a service request log window.

Example: Setting Up PowerShell Agent and Running a Test Task

The following example outlines how you can set up PowerShell Agent on a Windows server and run a test task.

Step 1

Create a Microsoft Windows Server 2008 R2 or 2012 R2 VM.

Step 2

Make sure that the VM has the required .NET Framework and Windows PowerShell versions.

Step 3

Open a web browser and log on to Cisco UCS Director.

Step 4

From the Administration > Virtual Accounts > PowerShell Agents tab, download the PowerShell Agent and install it on the VM.

Step 5

In Windows Firewall, open the port that has been configured for the PowerShell Agent (the default port is 43891) or stop the firewall.

Step 6

Open PowerShell and run the following commands:
Enable-PSRemoting -Force

Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*" -Force

Restart-Service WinRM

Set-ExecutionPolicy unrestricted -Force

Step 7

On the PowerShell Agent tab in Cisco UCS Director, click Execute Command option. In the Execute PowerShell Command dialog box, in addition to providing the IP address, user credentials of the VM, and the server domain, enter the following command in the Commands/Scripts field:
Echo "Import-ActiveDirectory" > c:\test.ps1

Step 8

Check the output for the test task on the C drive of the VM.

Preface

- Audience

- Conventions

- Related Documentation

- Documentation Feedback

- Obtaining Documentation and Submitting a Service Request

Audience

This guide is intended primarily for data center administrators who use Cisco UCS Director and who have responsibilities and expertise in one or more of the following:

- Server administration

- Storage administration

- Network administration

- Network security

- Virtualization and virtual machines

Conventions

Text Type

Indication

GUI elements

GUI elements such as tab titles, area names, and field labels appear in this font.

Main titles such as window, dialog box, and wizard titles appear in this font.

Document titles

Document titles appear in this font.

TUI elements

In a Text-based User Interface, text the system displays appears in this font.

System output

Terminal sessions and information that the system displays appear in this font.

CLI commands

CLI command keywords appear in this font.

Variables in a CLI command appear in this font.

[ ]

Elements in square brackets are optional.

{x | y | z}

Required alternative keywords are grouped in braces and separated by vertical bars.

[x | y | z]

Optional alternative keywords are grouped in brackets and separated by vertical bars.

string

A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

< >

Nonprinting characters such as passwords are in angle brackets.

[ ]

Default responses to system prompts are in square brackets.

!, #

An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

Note

Means reader take note. Notes contain helpful suggestions or references to material not covered in the document.

Caution

Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.

Tip

Means the following information will help you solve a problem. The tips information might not be troubleshooting or even an action, but could be useful information, similar to a Timesaver.

Timesaver

Means the described action saves time. You can save time by performing the action described in the paragraph.

Warning

IMPORTANT SAFETY INSTRUCTIONS

This warning symbol means danger. You are in a situation that could cause bodily injury. Before you work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with standard practices for preventing accidents. Use the statement number provided at the end of each warning to locate its translation in the translated safety warnings that accompanied this device.

SAVE THESE INSTRUCTIONS

Related Documentation

Cisco UCS Director Documentation Roadmap

For a complete list of Cisco UCS Director documentation, see the Cisco UCS Director Documentation Roadmap available at the following URL: Click Here .

Cisco UCS Documentation Roadmaps

For a complete list of all B-Series documentation, see the Cisco UCS B-Series Servers Documentation Roadmap available at the following URL: Click Here .

For a complete list of all C-Series documentation, see the Cisco UCS C-Series Servers Documentation Roadmap available at the following URL: Click Here .

Note

The Cisco UCS B-Series Servers Documentation Roadmap includes links to documentation for Cisco UCS Manager and Cisco UCS Central. The Cisco UCS C-Series Servers Documentation Roadmap includes links to documentation for Cisco Integrated Management Controller.

Documentation Feedback

To provide technical feedback on this document, or to report an error or omission, please send your comments to ucs-director-docfeedback@cisco.com. We appreciate your feedback.

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What's New in Cisco Product Documentation.

To receive new and revised Cisco technical content directly to your desktop, you can subscribe to the What's New in Cisco Product Documentation RSS feed. RSS feeds are a free service.

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Click Here . Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)