Tag Archives: Connect-Ucs

Cisco UCS PowerTool Suite – Part 2

In Part 1 of this series I covered the fundamentals of Cisco UCS PowerTool and how to make your first connection.  In Part 2 I expand on this and now show some of the basic commands you can use against UCSM when first learning to script with PowerTool.  With 4500+ commands, over 2300 just in the Cisco.UCSManager module alone it’s impossible to cover them all.  The intention here is not to show you them all but rather give you an idea of what’s out there and possible.

Cisco UCS PowerTool Suite – Part 1
Cisco UCS PowerTool Suite – Part 2
Cisco UCS PowerTool Suite – Part 3

In the below examples we will be working with the Cisco.UCSManager module.  We’re going to assume you’ve already made your connection to UCSM.  If you’re not sure how, checkout Part 1 of this series.

Now with our connection made one of the first commands we can try is Get-UCSChassis. This simply returns a list of all our UCS chassis’ in UCSM.

PowerTool C:\> Get-UcsChassis

AckProgressIndicator  : ack-not-in-progress
AdminState            : acknowledged
AssignedToDn          :
Association           : none
Availability          : available
ConfigState           : ok
ConnPath              : {A, B}
ConnStatus            : {A, B}
Discovery             : complete
DiscoveryStatus       : A,B
FabricEpDn            : fabric/server/chassis-6
Id                    : 6
LcTs                  : 1970-01-01T00:00:00.000
LicGP                 : 0
LicState              : license-ok
ManagingInst          : A
MfgTime               : not-applicable
Model                 : UCSC-C3X60-BASE

Above is a small extract of the output that comes back to us in list format.  This can be a little difficult to read if we have a few chassis’. We can clean this up a little by piping it to Format-Table and selecting our own columns.

PowerTool C:\> Get-UcsChassis | Format-Table RN, Id, Model, Availability, AdminState, Serial, ConfigState

Rn        Id Model           Availability AdminState   Serial ConfigState
--        -- -----           ------------ ----------   ------ -----------
chassis-3  3 UCSB-5108-AC2   unavailable  acknowledged CH29   ok
chassis-4  4 UCSC-C3X60-BASE available    acknowledged CH30   ok
chassis-5  5 N20-C6508       unavailable  acknowledged CH31   ok
chassis-6  6 UCSC-C3X60-BASE available    acknowledged CH32   ok

This now looks a little cleaner and provides us with information more relevant to what we might be after.

Next we can check what blades we have with Get-UCSBlade.  As with the previous command we can pipe it to Format-Table and select more meaningful columns.

PowerTool C:\> Get-UcsBlade | Format-Table DN, Model, NumofCPUs, NumofCores, TotalMemory

Dn                    Model            NumOfCpus NumOfCores TotalMemory
--                    -----            --------- ---------- -----------
sys/chassis-3/blade-1 UCSB-EX-M4-1             2         10       49152
sys/chassis-3/blade-3 UCSB-EX-M4-1             2         10       49152
sys/chassis-3/blade-7 UCSB-EX-M4-1             4         20       49152
sys/chassis-4/blade-1 UCSC-C3X60-SVRNB         2          8       49152
sys/chassis-4/blade-2 UCSC-C3X60-SVRNB         2          8       49152
sys/chassis-5/blade-4 UCSB-B200-M4             2          8       49152
sys/chassis-5/blade-5 UCSB-B420-M4             4         16       49152
sys/chassis-6/blade-1 UCSC-C3K-M4SRB           2          8       49152

If we have rack servers added into UCSM we can list them as well with Get-UcsRackUnit.  Or alternatively we can use Get-UcsServer to list both Blade and Rack servers in the one output display.

PowerTool C:\> Get-UcsServer | Format-Table AdminState, Model, operState, Serial, RN

AdminState Model            OperState    Serial Rn
---------- -----            ---------    ------ --
in-service UCSB-EX-M4-1     unassociated SRV72  blade-1
in-service UCSB-EX-M4-1     unassociated SRV73  blade-3
in-service UCSB-EX-M4-1     unassociated SRV75  blade-7
in-service UCSC-C3X60-SVRNB unassociated SRV76  blade-1
in-service UCSC-C3X60-SVRNB unassociated SRV77  blade-2
in-service UCSC-C220-M4S    unassociated RK32   rack-unit-1
in-service UCSC-C240-M4S    unassociated RK33   rack-unit-2
in-service UCSC-C220-M4S    unassociated RK34   rack-unit-3
in-service UCSC-C220-M4L    unassociated RK35   rack-unit-4
in-service UCSC-C220-M4L    unassociated RK36   rack-unit-5
in-service UCSC-C240-M4SX   unassociated RK37   rack-unit-6

Working with Orgs is very simple too with Get-UCSOrg.  In the below example I have just one root Org with is returned.

PowerTool C:\> Get-UcsOrg


Descr        :
Level        : root
Name         : root
PermAccess   : yes
Sacl         :
Ucs          : UCSPE-10-0-30-79
Dn           : org-root
Rn           : org-root
Status       :
XtraProperty : {}

Creating a new Org is just a matter of changing the ‘Get’ Verb to ‘Add’ using Add-UcsOrg

PowerTool C:\> Add-UcsOrg -Name Ukoticland


Descr        :
Level        : 1
Name         : Ukoticland
PermAccess   : no
Sacl         :
Ucs          : UCSPE-10-0-30-79
Dn           : org-root/org-Ukoticland
Rn           : org-Ukoticland
Status       : created
XtraProperty : {}

And you guessed it, we can remove an Org with the Remove Verb using Remove-UcsOrg

PowerTool C:\> Remove-UcsOrg -Org Ukoticland

Remove-UcsOrg
Are you sure you want to remove UCSPE-10-0-30-79:org-root/org-Ukoticland?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y


Descr        :
Level        : 1
Name         : Ukoticland
PermAccess   : yes
Sacl         :
Ucs          : UCSPE-10-0-30-79
Dn           : org-root/org-Ukoticland
Rn           : org-Ukoticland
Status       : deleted
XtraProperty : {}

Working with Service Profiles is extremely easy as well.  Get-UcsServiceProfile will display all service profiles. In the below example I have two.

PowerTool C:\> Get-UcsServiceProfile | Format-Table Name

Name
----
Production
Test

Creating an initial Service Profile is as simple as Add-UcsServiceProfile

PowerTool C:\> Add-UcsServiceProfile -Name MyFirstSP

And removing a Service Profile as simple as Remove-UcsServiceProfile

PowerTool C:\> Remove-UcsServiceProfile -ServiceProfile MyFirstSP
Are you sure you want to remove UCSPE-10-0-30-79:org-root/ls-MyFirstSP?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y

...
Dn                       : org-root/ls-MyFirstSP
Rn                       : ls-MyFirstSP
Status                   : deleted
XtraProperty             : {}

PowerTool has the ability to perform a number of different backups using Backup-Ucs.

The most complete form is full-state. Full state creates a binary file with a snapshot of the entire system. This type of backup can then be used to perform a full system restore to the Fabric Interconnect

PowerTool C:\> Backup-Ucs -Type full-state -PathPattern 'C:\cisco\ucspe-backup.tar.gz'

The second type of backup is config-logical which backs up information like service profiles, VLANs, VSANs, pools, and policies and is saved as an XML.

PowerTool C:\> Backup-Ucs -Type config-logical -PathPattern 'c:\cisco\ucspe-config-logical.xml'

The third is config-system. This includes all system configuration settings such as usernames, roles, and locales. This is also in XML format.

PowerTool C:\> Backup-Ucs -Type config-system -PathPattern 'c:\cisco\ucspe-config-all.xml'

The last is config-all. This is a combination of config-logical and config-system and once again saved as an XML.

PowerTool C:\> Backup-Ucs -Type config-all -PathPattern 'c:\cisco\ucspe-config-all.xml'

None of the XML backups are suitable for full system restores and do not contain passwords of accounts.

Finally, XML backups can be imported back in with Import-UcsBackup.

PowerTool C:\> Import-UcsBackup -LiteralPath 'C:\cisco\ucspe-config-all.xml' -Merge

This brings us to the end of the primer on UCS PowerTool cmdlets. Everything that we covered above was just a very small taste of what’s possible with Cisco UCS PowerTool. As mentioned in the beginning the intention was to get you thinking about what’s possible. There’s a wealth of information that can be retrieved from UCS with PowerTool. It’s not really a question of what I can retrieve but how I can retrieve it.

References
Cisco UCS PowerTool Suite
Cisco UCS PowerTool Suite Communities Page

Cisco UCS PowerTool Suite – Part 1

I thought I would created a short blog series on a very underrated collection of PowerShell modules from Cisco called the Cisco UCS PowerTool Suite.  The UCS PowerTool Suite was released back in early 2013 and has been steadily growing and maturing since.   The current release of the PowerTool Suite, as of this blog post, is 2.2.1 which contains 5 modules and over 4500 Cmdlets!   Yes that’s right, over 4500 Cmdlets, crazy huh.

PowerTool brings PowerShell and all its goodness to Cisco UCS and allows you to script and automated your UCS management is a very powerful way.  PowerTool can connect to Cisco UCS Manager, UCS Central and UCS IMC (namely C-Series and E-Series).  PowerTool isn’t doing anything special behind the scenes.  It connects via the standard XML APIs that the Java GUI uses to connect to things like UCS Manager, as well as respecting and working with the Management Information Tree (MIT) that UCS is built on.

In Part 1 of this series I run through the basics of installing UCS PowerTool and connecting to your first UCS Manager.

Before you install the UCS PowerTool Suite you need to meet a few requirements.  PowerTool is not currently compatible with PowerShell Core so at present you will need a Windows box running the following.

  • Windows PowerShell 3.0 or higher
  • .NET Framework Version 4.5 or higher
  • PowerShell 4.0 and higher for the DSC module resources

Once you met these requirements you can download the latest version of UCS PowerTool from Cisco.  Then proceed to install from the MSI file.  The installation wizard is straight forward and will copy the modules to your C:\Program Files (x86)\WindowsPowerShell\Modules folder along with three shortcuts to your desktop.  Each shortcut, Cisco IMC PowerTool, Cisco UCS Central PowerTool, and Cisco UCS Manager PowerTool, runs a small startup script that basically loads their respective module.

We don’t need to actually use these shortcuts if we choose not to.  We can just run PowerShell as we normally would and import the modules as needed.  If we’re running Windows Server, though,  these module will actually auto load for us.

Below is what we see when we use the shortcut, Cisco UCS Manager PowerTool.

Below we will delve into connecting to our first UCS Manager, but first let’s run through a few of the basics.  First we run Get-Module -ListAvailable.  This will show us all the modules available on our system.  Below we can see the five Cisco modules we just installed.

PowerTool C:\> Get-Module -ListAvailable

    Directory: C:\Program Files (x86)\WindowsPowerShell\Modules


ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Binary     2.2.1.8    Cisco.IMC                           {FnResetImcPowerProfile, FnTestImcLd...
Binary     2.2.1.8    Cisco.UCS.Core                      {Add-UcsHardwareProfile, Get-UcsPowe...
Manifest   2.2.1.8    Cisco.UCS.DesiredStateConfiguration {Get-UcsConnection, Get-ImcConnection}
Binary     2.2.1.8    Cisco.UCSCentral                    {Connect-UcsCentral, Disconnect-UcsC...
Binary     2.2.1.8    Cisco.UCSManager                    {Connect-Ucs, Disconnect-Ucs, Start-...
Script     1.0.1      Microsoft.PowerShell.Operation.V... {Get-OperationValidation, Invoke-Ope...
Binary     1.0.0.1    PackageManagement                   {Find-Package, Get-Package, Get-Pack...
Binary     1.0.0.0    PackageManagement                   {Find-Package, Get-Package, Get-Pack...
Script     3.4.0      Pester                              {Describe, Context, It, Should...}
Script     1.0.0.1    PowerShellGet                       {Install-Module, Find-Module, Save-M...


PowerTool C:\>

Next we run Get-Command -Module Cisco.UcsManager.  This displays all the Cmdlets inside this module, all 4500+ of them!  Once you’ve memorised them all we can move on… just kidding 🙂

PowerTool C:\> Get-Command -Module Cisco.UcsManager
...
Cmdlet          Set-UcsWwnInitiator                                2.2.1.8    Cisco.UCSManager
Cmdlet          Set-UcsWwnPool                                     2.2.1.8    Cisco.UCSManager
Cmdlet          Start-UcsGuiSession                                2.2.1.8    Cisco.UCSManager
Cmdlet          Start-UcsKvmSession                                2.2.1.8    Cisco.UCSManager
Cmdlet          Start-UcsServer                                    2.2.1.8    Cisco.UCSManager
Cmdlet          Start-UcsTransaction                               2.2.1.8    Cisco.UCSManager
Cmdlet          Stop-UcsServer                                     2.2.1.8    Cisco.UCSManager
Cmdlet          Sync-UcsManagedObject                              2.2.1.8    Cisco.UCSManager
Cmdlet          Undo-UcsTransaction                                2.2.1.8    Cisco.UCSManager
Cmdlet          Update-UcsCatalogue                                2.2.1.8    Cisco.UCSManager
Cmdlet          Update-UcsFirmware                                 2.2.1.8    Cisco.UCSManager
Cmdlet          Watch-Ucs                                          2.2.1.8    Cisco.UCSManager

PowerTool C:\>

To connect to our UCSM we use the Cmdlet Connect-Ucs. To find out how to do this we can use Get-Help to find example syntax.

PowerTool C:\> get-help connect-ucs

NAME
    Connect-Ucs

SYNOPSIS
    Connects to a UCS


SYNTAX
    Connect-Ucs [-Name] <string[]> [-Credential] <PSCredential> [-Port <ushort>] [-NoSsl]
    [-NotDefault] [-Proxy <WebProxy>] [<CommonParameters>]

    Connect-Ucs -LiteralPath <string> -Key <SecureString> [-NotDefault] [-Proxy <WebProxy>]
    [<CommonParameters>]

    Connect-Ucs -Path <string> -Key <SecureString> [-NotDefault] [-Proxy <WebProxy>]
    [<CommonParameters>]


DESCRIPTION
    Connects to a UCS. The cmdlet starts a new session using the specified parameters. One can
    have more than one connections to a server. PowerTool Supports working with multiple default
    servers. This can be enabled by setting SupportMultipleDefaultUcs using
    Set-UcsPowerToolConfiguration.

We’re now ready to make our first connection.  In the below example we connect using the Cmdlet Connect-Ucs and save the connection to the variable $handle1.  This gives us the flexibility to connect to multiple UCSM devices at the same time and run commands against them.  Something which I’ll cover more on in a future post.

PowerTool C:\> $handle1 = Connect-Ucs -Name 10.1.1.1

Running the command gives a credential request dialog box. Enter in the same credentials you normally would when connecting to your UCSM.

If we run Get-UcsPSSession we can display our current session details.  Here you can see that we’re connected to UCS UCSPE-10-1-1-11

PowerTool C:\> Get-UcsPSSession

NumPendingConfigs : 0
Ucs : UCSPE-10-1-1-11
Cookie : 1494751391/e26549b0-557a-4ba7-83a8-c1ae36468ebb
Domains : org-root
LastUpdateTime : 14-May-17 6:43:14 PM
Name : 10.0.30.77
NoSsl : False
NumWatchers : 0
Port : 443
Priv : {aaa, admin, ext-lan-config, ext-lan-policy...}
PromptOnCompleteTransaction : False
Proxy : 
RefreshPeriod : 600
SessionId : 
TransactionInProgress : False
Uri : https://10.1.1.11
UserName : ucspe
Version : 3.1(2b)
VirtualIpv4Address : 10.1.1.11
WatchThreadStatus : None

Here’s where things get a little interesting.  We can export this session to an XML file, using Export-UcsPSSession, and with a secure key we can connect to our UCS in the future without providing credential details.

In the below example we export our current session to an XML file called ucspe.xml and type in a secure key.  Next using ConvertTo-SecureString we can export the key we used to a file called ucspe.key which we can use to decrypt our password in the XML file.

PowerTool C:\> Export-UcsPSSession -LiteralPath C:\cisco\ucspe.xml
cmdlet Export-UcsPSSession at command pipeline position 1
Supply values for the following parameters:
Key: ********

PowerTool C:\> ConvertTo-SecureString -String "Password" -AsPlainText -Force | ConvertFrom-SecureString | Out-File ucspe2.key

Now we can use our key file and our XML file to connect to our UCSM without being prompted for credentials.


PowerTool C:\> $key = ConvertTo-SecureString (Get-Content C:\cisco\ucspe.key)

PowerTool C:\> $handle1 = connect-ucs -Key $key -LiteralPath C:\cisco\ucspe.xml

The key file should, of course, be treated as highly sensitive.  Steps should be taken to protect unauthorized people accessing and reading this file.  I find a good way to protect it is by locking down permissions on the file and folder where the XML and key file are stored.  In my case only myself and the Scheduled Task account that requires it can access the file.

Last we should know how to cleanly disconnect from our UCSM session.  This simply requires the use of Disconnect-Ucs.  In the below example we also reference our session in the variable $handle1 which is good practice if we are connecting to multiple UCSM devices.


PowerTool C:\> Disconnect-Ucs -Ucs $handle1

In Part 1 of this series I cover the minimum requirements you need on your system before install PowerTool.  I then go through the fundamental basics of making your first connection to a UCS Manager. Then taking it one step further and showing how we can future connect without providing credentials. Finally I show how to disconnect from the UCSM. In Part 2 of this series I will run through the basics of querying information from UCSM via some of the 4500+ Cmdlets.

Cisco UCS PowerTool Suite – Part 1
Cisco UCS PowerTool Suite – Part 2
Cisco UCS PowerTool Suite – Part 3

References
Cisco UCS PowerTool Suite
Cisco UCS PowerTool Suite Communities Page